Simple command-line utility to automate applying tags and covers to mp3 files
Simple command-line utility to automate applying tags and covers to mp3 files
For music content creators, generating new mp3 files is a common routine. Opening those fresh files in iTunes or any other media applications simply to edit tags and apply a cover can be a tedious and repeditive task. Especially if you are regenerating the file after changes.
mp3-stamp lets you create a small .mp3.json file which contains all the tag info you want to write (including specifying cover images). Keep that file next to your audio file and just run this tool (globally) to apply the tags quickly and easily.
Imagine we have an audio project folder called my-audio-project and inside is a new mp3 file called my-song.mp3 that we generated from our favourite audio software (DAW). We want to add this to our music library, or share it but first we need tags and a cover. It may be ok to edit these tags and apply a cover in iTunes (or similar media app or tag editor), but if we overwrite this file (eg. making an updated version) we have to repeat this process through a UI over and over again. Instead, let's use a small .mp3.json file which lives in the same folder where we generate our mp3 file, and use that config file to specify the tags and cover, similar to a preset or defaults. Then every time we recreate the file, we just run this command line tool and apply the metadata.
Noice! Much quicker, less friction to our creation process. Just write those tags and set that cover like a boss.
Install the tool globally to be able to use the mp3stamp command from the terminal at any location *.
npm install mp3-stamp -g
* you may need to restart your terminal to be able to use the mp3stamp command from any path after first install. If you get "Command not found..." type errors, this is likely the case.
To use this tool, just open up a terminal and run the mp3stamp command. The next few sections describe the options available.
By default this tool looks in the current working directory for *.mp3 and *.mp3.json files.
If you wish to run the tool from a different directory, specify the base path as a relative or absolute path.
mp3-stamp ../../my-audio-project
If you want to create a config file for an mp3, just pass the --create option.
You can also use this argument with or without the basePath argument (eg. if you wish to create a config file in a different location to the current working directory).
mp3stamp --create
This will ask you to pick an mp3 file from the current working (or base) path, and will ask some basic questions to prefill the most common tags.
You can also pick a cover file if any are present. It will then create a template config from the same mp3 filename.
You can open the file for edit to refine the tag data, and delete any unused tags you, or just leave them null.
You also have the option of applying the new data straight to mp3 file, if you don't need anymore editing.
You can of course manually create and edit the file and write the data you need (according to the schema described later).
NOTE: If you are manually creating the config file then you must ensure the filename is the same as the mp3, but with a .json extension. The tool uses this convention to find files.
Passing this option will stamp (write info from .json file to .mp3 file) all the .mp3 files in the current directory.
This is useful if you keep your mp3s in a common folder, such as a mixdowns folder. You can keep all your config files next to them and just overwrite the mp3 and run mp3stamp --batch to update all files at once.
mp3stamp --batch
Given our example of a folder with an mp3 inside called my-song.mp3 and a config file called my-song.mp3.json, open up a terminal and run the mp3stamp command.
mp3-stamp
You will be asked to select the mp3 file, and the config file matching the same mp3 filename plus .json will be selected for your tags and covers to be applied.
The tool supports the <artist> - <title>.mp3 format. If files are named this way, the artist and title info will be prefilled when using the --create option.
The .json configuration file is just a simple json file with some top level keys, and other grouped keys. The grouped keys are song, album, webpage, and cover. This helps organise tags by context.
Here is a list of all the supported tags and their expected types - Note you can just specify null for any tags you don't want to specify, but want to leave in the file for reference (eg. you are copying a base template to make new configuration files).
stringstring[]string[]string[]stringinteger - (ms)stringstringstring - ("1" or "1/3")string - (DDMM)integer - (YYYY)string (conductor/performer refinement)string (interpreted, remixed, or otherwise modified by)string - (eg. "Dm", "Eb")stringstring (international standard recording code)string (copyright message)string (commercial information)string (copyright/Legal information)integer (beats per minute)stringstring (official artist/performer webpage)string (official audio file webpage)string (official audio source webpage)string (official internet radio station homepage)string (publishers official webpage)stringstring - (32x32 pixels 'file icon' PNG only)string - (Other file icon)string - (main cover image used by most media applications like iTunes etc)stringstringstring - (e.g. lable side of CD)string - (Lead artist/lead performer/soloist)string - (Artist/performer)stringstring - (Band/Orchestra)stringstring - (Lyricist/text writer)string - (Recording Location)string - (During recording)string - (During performance)string - (Movie/video screen capture)string - (A bright coloured fish)stringstring - (Band/artist logotype)string - (Publisher/Studio logotype)Covers can be relative or absolute jpg file path (except for cover.icon-file which is PNG only).
Here is an example of a *.mp3.json config file:
{
"song": {
"title": "song-title",
"artists": ["song-artist-1", "song-artist-2"],
"composers": ["song-composer-1", "song-composer-2"],
"genres": ["song-genre-1", "song-genre-2"],
"number": "1/6",
"duration": 1000
},
"album": {
"title": "album-title",
"artist": "album-artist",
"disc": "1/1",
"release-date": 1012,
"release-year": 2019
},
"conductor": "conductor",
"remixed-by": "remixed-by",
"publisher": "publisher",
"key": "Dm",
"media-type": "media-type",
"isrc": "isrc",
"copyright": "copyright",
"commercial": "commercial",
"legal": "legal",
"bpm": 100,
"payment": "payment",
"webpage": {
"artist": "webpage-artist",
"audio-file": "webpage-audio-file",
"audio-source": "webpage-audio-source",
"internet-radio": "webpage-internet-radio",
"publisher": "webpage-publisher"
},
"cover": {
"other": null,
"icon-file": null,
"icon-other": null,
"front": "cover.jpg",
"back": null,
"leaflet": null,
"media": null,
"soloist": null,
"artist": null,
"conductor": null,
"group": null,
"composer": null,
"lyricist": null,
"location": null,
"recording": null,
"performance": null,
"video-capture": null,
"fish": null,
"illustration": null,
"logo-artist": null,
"logo-publisher": null
}
}
FAQs
Simple command-line utility to automate applying tags and covers to mp3 files
We found that mp3-stamp demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.