tone is a cross platform audio tagger and metadata editor to dump and modify metadata for a wide variety of formats, including mp3, m4b, flac and more.
README
tone
tone is a cross-platform audio tagger and metadata editor to dump and modify metadata for a wide variety of formats, including mp3, m4b, flac and more. It has no dependencies and can be downloaded as single binary for Windows, macOS, Linux and other common platforms.
The code is written in pure C# and utilizes the awesome atldotnet library to provide full support for a wide variety of audio and metadata formats.
Features
The main purpose of tone is to tag m4b audio books for myself. It is planned as a successor to [m4b-tool].
dump metadata of audio files
different metadata formats (e.g. chptfmtnative, ffmetadata, etc.)
file information (bitrate, channels, duration, etc.)
support for filterable json output (similar to jq)
extensive list of supported tags (default fields like album or *artist as well as custom fields, covers, chapters, etc.)
tag audio files with different kinds of metadata
different file formats (e.g. mp3, m4b, and flac)
extensive list of supported tags (default fields like album or *artist as well as custom fields, covers, chapters, etc.)
filename to tags via --path-pattern (see below)
custom javascript taggers via --script and --script-tagger-parameter
Support me via GitHub sponsors
If you are using any of my projects and find them helpful, please consider donating to support me. I plan to use the money to support other open source projects or charitable purposes. Thank you!
TL;DR
dump tags
# show help
tone dump --help
# show all tags for single file (input.mp3)
tone dump input.mp3
# show title and artiest tag recursively for all files in directory with extension m4b in FFMETADATA format
tone dump audio-directory/ --include-extension m4b --format ffmetadata --include-property title --include-property artist
# show album only via json format and JSONPath query
tone dump "input.mp3" --format json --query "$.meta.album"
# show audio stream information via JSONPath query
tone dump "input.mp3" --format json --query "$.audio"
IMPORTANT: Because metadata is modified in place without copying the
file, changes are only safe on local block storage (like your hard disk, sd card, etc.). Modifying files on
remote storages (like network shares) may break your files. Please make sure you have a backup.
tone is a terminal application and deployed as monolithic binary with no dependencies.
This means, that downloading a single file from the releases page.
Linux / macOS
# linux-arm
wget https://github.com/sandreas/tone/releases/download/v0.2.5/tone-0.2.5-linux-arm.tar.gz
# linux-arm64
wget https://github.com/sandreas/tone/releases/download/v0.2.5/tone-0.2.5-linux-arm64.tar.gz
# linux-x64
wget https://github.com/sandreas/tone/releases/download/v0.2.5/tone-0.2.5-linux-x64.tar.gz
# macos (m1) - not working atm, see issue #6
wget https://github.com/sandreas/tone/releases/download/v0.2.5/tone-0.2.5-osx-arm64.tar.gz
# macos (intel)
wget https://github.com/sandreas/tone/releases/download/v0.2.5/tone-0.2.5-osx-x64.tar.gz
# untar
tar xzf tone-*.tar.gz
# install to your $PATH
sudo mv tone*/tone /usr/local/bin/
# test if tone is usable
tone --help
Windows
# download for windows (powershell)
iwr -outf tone-0.2.5-win-x64.zip https://github.com/sandreas/tone/releases/download/v0.2.5/tone-0.2.5-win-x64.zip
# extract tone
Expand-Archive -LiteralPath tone-0.2.5-win-x64.zip -DestinationPath .
# test if tone is usable
.\tone --help
# open directory in windows explorer to manually put tone in your %PATH%, e.g. C:\Windows
start .
Docker
Since tone is a monolith, it is probably not necessary to run it via docker, but since it is convenient to have a possibility to copy tone in your own image, I published an official variant on dockerhub. Since it is a multiarch image, you can use it on arm6, arm7, aarch64, and x64 images.
docker pull sandreas/tone:v0.2.5
Or to use tone in your custom Dockerfile:
# Dockerfile
FROM sandreas/tone:v0.2.5 as tone
# ...
COPY --from=tone /usr/local/bin/tone /usr/local/bin/
Reserved fields and supported formats
tone already supports some common input and output formats for metadata, as well as a tone specific one (ToneJson). Moreover tone also uses some reserved metadata fields to overcome issues when storing specific information.
Reserved metadata fields
The namespace ----:com.pilabor.tone as well as the following fields are reserved for tone in mp4 / m4a / m4b based file formats:
----:com.pilabor.tone:AUDIBLE_ASIN: Since there is no official field for storing the audible ASIN, tone MAY use this custom field to store this piece information
----:com.pilabor.tone:PART: Since the movement index is often used for a part of a series but only supports integers (e.g. 1) it cannot store some series part names (e.g. 2.1 or roman numbers like IV)
tone supports --meta-part parameter being a fallback for storing non integer values while coincidentally storing --meta-movement only if it is an integer value
Therefore it is always recommended to use the --meta-part parameter instead of --meta-movement to set the part number of a series
ToneJson format
The ToneJson format is specific for tone, can contain all supported metadata (including binary images) and looks similar to this example...
The ChptFmtNative format was initially used in mp4v2, but never fully specified. However, there is a loose spec here.
Example
## artist: Cœur de pirate
## album: Blonde
##
## total-duration: 00:38:37.034
##
00:00:00.000 Lève les voiles
00:01:12.709 Adieu
00:03:40.346 Danse et danse
00:06:50.775 Golden Baby
00:09:57.772 Ava
00:13:14.657 Loin d'ici
00:15:58.494 Les amours dévouées
00:18:26.443 Place de la république
00:22:37.664 Cap diamant
00:25:20.925 Verseau
00:29:14.722 Saint-Laurent
00:32:29.519 La petite mort
00:36:19.140 Hôtel amour
ffmetadata format
The ffmetadata format was designed for ffmpeg, a versatile media encoder and it is specified here.
Example
;FFMETADATA1
title=Back in Black
artist=AC/DC
track=6/10
album=Back in Black
disc=1/1
date=1986
genre=Hard Rock
TBPM=0
compilation=0
TMED=CD
language=eng
album_artist=AC/DC
artist-sort=AC/DC
publisher=Atlantic
TIPL=arranger
TDOR=1980-07-25
encoded_by=LAME 3.99.5
Script=Latn
Artist Credit=AC/DC
ALBUMARTISTSORT=AC/DC
CATALOGNUMBER=16018-2
Commands
The features of tone are divided by commands. You can dump information or tag a file and so on. To do so, run
tone
Example:
tone dump "my-audio-file.mp3"
global options
There are some global options, that can be used to change the behaviour of the file iterator. These options apply for all commands:
--order-by: Sort files by attribute (defaults to path, available options are path, size, filename, extension, created, modified, accessed, combine via ,, descending via !), examples:
--order-by="!created" - sort by create date descending
--order-by="extension,created" - sort by extension, then by created
--order-by="size,!extension,modified" - sort by size, then extension descending, then by modification date
--limit: Limit results
one value (e.g. --limit=10) - top 10 results
two values with comma (e.g. --limit=10,20) - offset 10 fetch 20 results
--include-extensions: Filter for these extensions
--debug: Enable debug mode (for development or issue reporting)
--force: Try to force action (e.g. overwrite existing files, etc.)
dump - show audio metadata
The dump command can be used to show metadata for a wide variety of audio files. You can either specify a single file or a directory,
which will be traversed recursively. Several output --format options are supported. By default a terminal user interface library is used,
but it is also possible to use json or ffmetadata.
Options reference
tone dump --help
USAGE:
tone dump [input] [OPTIONS]
EXAMPLES:
tone dump --help
tone dump input.mp3
tone dump audio-directory/ --include-extension m4b --format ffmetadata --include-property title --include-property artist
ARGUMENTS:
[input] Input files or folders
OPTIONS:
-h, --help Prints help information
--debug
--force
--include-extension
--order-by
--limit
--include-property
--format
--query
> IMPORTANT: tone is meant to be used on local block storage and may cause unwanted side effects when trying to modify tags on network or
> other remote storage. Please ensure you have a backup or copy files locally to change metadata. See #52 for details.
The --taggers option
The --taggers option allows you to specify a custom set or a different order of internal taggers (NOT input formats), which are gonna be applied. In most cases
changing the order of the taggers does not make a huge difference, but fully understanding this option
requires a bit of technical knowledge. Let's go through a use case to see what you can do with it.
> Note: Internal taggers are applied in a sane order by default and not meant for beginners. Most of the time you don't need to change the order and this usually is for very specific experts use cases. So if you don't fully understand this option, just leave it as is.
Use case: re-tag sorttitle / sortalbum
The following taggers are relevant for this use case:
remove - Removes metadata fields or sets it to an empty value
m4bfillup - Fills up missing or relevant special fields for audio books (e.g. sorttitle / sortalbum)
* - Represents all remaining taggers, that are not already provided by name
Usually, the remove tagger is applied at last. If you provide --meta-remove-property=sorttitle, this ensures an existing value will really be
removed after all taggers have been applied. The m4bfillup tagger will automatically generate sorttitle / sortalbum from movementname,
movement and title / album if AND ONLY IF the current value is empty.
So if you change the movementname (e.g. Harray Potter to Harry Potter because of a typo), sorttitle / sortalbum will not be updated,
because these fields already have a value. If you remove the sorttitle / sortalbum, it will not be auto-updated but only removed,
since remove is applied after m4bfillup.
This can be solved by reordering the taggers:
First apply remove tagger to remove sorttitle / sortalbum completely
Then apply m4bfillup to rebuild sorttitle / sortalbum
tone tag harry-potter-1.m4b --taggers="remove,m4bfillup" --meta-movement-name="Harry Potter" --meta-remove-property="sortalbum" --meta-remove-property="sorttitle"
As you see, most of the time, you only care about one special tagger to be applied first or last. This is why tone has an option to add all
remaining taggers to the list using a *:
tone tag harry-potter-1.m4b --taggers="remove,*" --meta-movement-name="Harry Potter" --meta-remove-property="sortalbum" --meta-remove-property="sorttitle"
The following taggers are available at the moment (names can be applied case-insensitive):
ToneJson - sets metadata values from tone.json file
Metadata - sets metadata values from input parameters --meta-...
Id - sets metadata values from --id (e.g. for fetching from web sources via custom js taggers)
Cover - sets cover from cover files
PathPattern - sets metadata values from path pattern
Ffmetadata - sets metadata values from ffmetadata.txt file
ChptFmtNative - sets chapters from chapters.txt file
Equate - equates 2 or more metadata fields from --meta-equate (see below)
M4BFillUp - auto fill album, title, iTunesMediaType from existing fields if possible
PrependMovementToDescription - prepends movement to all description fields, if set
Remove - removes metadata values from input parameter --meta-remove-property and --meta-remove-additional-field
ScriptTagger - your personal custom JavaScript taggers (see below)
Equate
The equate tagger can be used to set a field by referencing another, e.g. when you would like to set
the AlbumArtist equal to the Artist, you could use --meta-equate "artist,albumartiest".
The --meta-equate works like this:
Fields to equate are separated by ,, at least 2 fields are required, but more are allowed
The first field contains the value, the latter fields will be overwritten by this value
The --meta-equate parameter can be used multiple times to equate multiple fields, e.g. --meta-equate=fieldA,fieldB --meta-equate=fieldC,fieldD,fieldE
The provided field names are treated case-insensitive, see reference below
Field reference
Album
AlbumArtist
Artist
Bpm
ChaptersTableDescription
Composer
Comment
Conductor
Copyright
Description
DiscNumber
DiscTotal
EncodedBy
EncoderSettings
EncodingTool
Genre
Group
ItunesCompilation
ItunesMediaType
ItunesPlayGap
LongDescription
Lyrics
Part
Movement
MovementName
Narrator
OriginalAlbum
OriginalArtist
Popularity
Publisher
PublishingDate
PurchaseDate
RecordingDate
SortTitle
SortAlbum
SortArtist
SortAlbumArtist
SortComposer
Subtitle
Title
TrackNumber
TrackTotal
It is possible to use the tag subcommand with multiple --path-pattern arguments to read metadata from path names. Please note:
If multiple path patterns are present, the first matching one is preferred
Path patterns can be applied recursively for a whole directory tree as well as for single files
It is recommended use the --dry-run flag to see a diff before changing anything
there is an issue with flags like --dry-run, that they sometimes not work depending on the position - sometimes shifting them around helps
Path pattern matching is based on grok.net, so all metadata properties could be read from a path name and there are a lot of things yet to be documented
For now it is recommended to use the short hands below
short hands
All short hands are configured to match non-slash (/) or part numbers ([0-9-.IVXLCDM]+).
%a - Artist
%A - SortArtist
%c - Comment
%C - Copyright
%d - Description
%D - LongDescription
%g - Genre
%m - Album
%M - SortAlbum
%n - Title
%N - SortTitle
%p - Part (only matching part numbers)
%s - MovementName
%t - AlbumArtist
%w - Composer
%y - ReleaseDate
%z - IgnoreDummy
%Z - IgnoreDummy (only matching part numbers)
Custom scripted taggers (experimental)
With tone v0.0.4 it is possible to use scripted taggers. Long story short: You can now use JavaScript
to hook into the tagging mechanism and write your own extensions for tone.
> Note: script support is limited to a specific subset of JavaScript and does not support every feature that is supported in modern browsers. If you would like to know more, take a look at jint
create a javascript file
Lets say you would like to consume an external API to set some tags, in our example we use http://musicbrainz.org to tag the audiobook Harry Potter and the Philosophers Stone :
// musicbrainz.js
function musicbrainz(metadata, parameters) {
// e2310769-2e68-462f-b54f-25ac8e3f1a21
var id = parameters.length > 0 ? parameters[0] : null;
if(id === null) {
console.log("Please provide a valid musicbrainz release id to use this tagger");
return;
}
var url = "http://musicbrainz.org/ws/2/release/" + id + "?inc=recordings&fmt=json";
console.log("fetching url:", url);
// User-Agent header is required for musicbrainz to provide a response
var json = tone.Fetch(url, {
headers: {
'User-Agent': 'Mozilla/5.0 (iPad; U; CPU OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4'
}
});
// you could also read a text file in the base path of the audio file
// json = tone.ReadTextFile(metadata.BasePath + "/musicbrainz.json");
var result = JSON.parse(json);
metadata.Title = result.title;
console.log("new title:", result.title);
if('barcode' in result) {
metadata.AdditionalFields["ISBN"] = result.barcode;
console.log("new barcode:", result.barcode);
}
}
// register your function name as tagger
tone.RegisterTagger("musicbrainz");
run your tagger
Now you can use the --script parameter to load your custom JavaScript and furthermore
the --script-tagger-parameter to provide the parameters array used in the tagger function.
If you would like to prevent the default tone taggers to be applied, you can also limit the
them to your scripted one via --taggers=musicbrainz.
tone tag "harry-potter-1.m4b" --taggers="musicbrainz" --script="musicbrainz.js" --script-tagger-parameter="e2310769-2e68-462f-b54f-25ac8e3f1a21"
Tagger API
To get an overview of fields, that can be accessed or modified via the metadata object, you should take a look at the IMetadata interface. Not all of them are primitive types, but there are API at least some helper methods to overcome this problem (more are planned):
Method
Description
Notes
tone.RegisterTagger(string functionName):void
Registers a custom tagger function with functionName
-
tone.Fetch(string url [, object? options]):string
Fetches remote url contents using options inspired by original fetch API
Only a small subset of options is implemented (mainly method, body and headers)
Appends text to a file (create file if not exists, append contents)
-
tone.LimitByteLength(string message, int maxLength):string
Limites text to byte length (not char length)
-
tone.CreateDateTime(string dateString):DateTime
Creates a DateTime value from string
e.g. for metadata.PublishingDate
tone.CreateTimeSpan(number milliseconds):TimeSpan
Creates a TimeSpan value from string
e.g. for metadata.TotalDuration
tone.CreatePicture(string path):PictureInfo
Creates a PictureInfo value from a path (refer to Download)
for metadata.EmbeddedPictures
tone.CreateChapter(string title, number startMs, number lengthMs [, PictureInfo picture, string subtitle, string uniqueID]):ChapterInfo
Creates a ChapterInfo
for metadata.Chapters
Development
Setup environment
To build tone, you need the dotnet SDK with at least version 6.0. After this you check out the code via git and that's it.
# check dotnet version > 6.0
dotnet --version
# clone git repository
git clone https://github.com/sandreas/tone.git
# change into main solution
cd tone
# restore nuget packages
dotnet restore
# build solution
dotnet build
First test and using an IDE
Run tone without params to test your environment
# change to project tone/tone
cd tone
# run the project
dotnet run
# output should be something like:
# USAGE:
# tone [OPTIONS]
# ...
If this works, you can now open the tone.sln file in the main directory with your favorite IDE (e.g. Visual Studio, JetBrains Rider or Visual Studio Code)
Publish a binary
You can now also publish tone as single binary. Before you build an executable binary, you have to choose a valid runtime identifier (RID)
for the operating system and the architecture you would like to build for.
Valid RID values are for example win-x64, linux-x64, osx-x64 and so on
Refer to the official RID catalog and please ensure, your RID is supported by the according dotnet version (older versions may not support modern runtime ids)
