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!

<p align="center"> <a href="https://github.com/sponsors/sandreas"><img src="./assets/help.svg" width="300" alt="sponsor me and donate" style="margin:auto;"></a> </p>

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"

modify tags

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.

# show help
tone tag --help

# change title tag
tone tag input.mp3 --meta-title "a title"

# change a custom field, auto-import covers nearby and show debug info on error (--dry-run simulation)
tone tag --debug --auto-import=covers --meta-additional-field "©st3=testing" input.m4b --dry-run

# recursively set tags genre, artist, series, part and title by path pattern (--dry-run simulation)
tone tag --auto-import=covers --auto-import=chapters --path-pattern="audiobooks/%g/%a/%s/%p - %n.m4b" --path-pattern="audiobooks/%g/%a/%z/%n.m4b" audiobooks/ --dry-run

# write your own custom JavaScript tagger and call this function with parameters to modify metadata on your own
tone tag "harry-potter-1.m4b" --taggers="musicbrainz" --script="musicbrainz.js" --script-tagger-parameter="e2310769-2e68-462f-b54f-25ac8e3f1a21"

Setup

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...

Example

{
  "audio": {
    "bitrate": 320,
    "format": "MPEG Audio (Layer III)",
    "formatShort": "MPEG",
    "sampleRate": 44100.0,
    "duration": 255920.0,
    "channels": {
      "count": 2,
      "description": "Joint Stereo"
    },
    "frames": {
      "offset": 20749,
      "length": 10236864
    },
    "metaFormat": [
      "id3V24"
    ]
  },
  "meta": {
    "album": "Back in Black",
    "albumArtist": "AC/DC",
    "artist": "AC/DC",
    "discNumber": 1,
    "discTotal": 1,
    "encodedBy": "LAME 3.99.5",
    "genre": "Hard Rock",
    "itunesCompilation": "no",
    "publisher": "Atlantic",
    "recordingDate": "1986-01-01T00:00:00",
    "sortArtist": "AC/DC",
    "title": "Back in Black",
    "trackNumber": 6,
    "trackTotal": 10,
    "embeddedPictures": [
      {
        "type": 2,
        "code": 3,
        "mimetype": "image/jpeg",
        "data": "/9j/4AAQSkZJRgA...9k="
      }
    ],
    "additionalFields": {
      "grP1": "5",
      "tmed": "CD",
      "tlan": "eng",
      "tipl": "arranger",
      "tdor": "1980-07-25",
      "script": "Latn",
      "artist Credit": "AC/DC",
      "albumartistsort": "AC/DC",
      "catalognumber": "16018-2",
      "album Artist Credit": "AC/DC",
      "musicBrainz Album Type": "album",
      "replaygaiN_ALBUM_GAIN": "-8.43 dB",
      "replaygaiN_ALBUM_PEAK": "1.064363",
      "replaygaiN_TRACK_GAIN": "-8.38 dB",
      "replaygaiN_TRACK_PEAK": "1.051585",
      "musicBrainz Album Status": "Official",
      "musicBrainz Album Release Country": "DE",
      "acoustid Id": "8b379144-9a9d-4fc1-897a-a7c0771f8ebb",
      "musicBrainz Album Id": "fdabb997-b984-4097-bd3b-89fafd5e2e75",
      "ufid": "http://musicbrainz.org\u0000ef71afb6-5e51-41df-999b-9e7c7306063a",
      "musicBrainz Artist Id": "66c662b6-6e2f-4930-8610-912e24c63ed1",
      "musicBrainz Album Artist Id": "66c662b6-6e2f-4930-8610-912e24c63ed1",
      "musicBrainz Release Group Id": "d3bc1a64-7561-3787-b680-0003aa50f8f1",
      "musicBrainz Release Track Id": "cf05ab29-27c7-47ed-9450-9f4de676cded",
      "acoustid Fingerprint": "AQADtE...oIIYgRUChBhABIEeWAA0AQR4hSDg",
      "iTunNORM": " 00001AE7 00001AE7 00004340 00004340 00000000 00000000 0000869A 0000869A 00000000 00000000"
    }
  },
  "file": {
    "size": 10257613,
    "created": "2019-06-12T18:50:37.5527895+02:00",
    "modified": "2019-06-12T18:50:37.5527895+02:00",
    "accessed": "2023-02-14T09:21:29.2261032+01:00",
    "path": "music/album/AC_DC/Back in Black",
    "name": "06 - Back in Black.mp3"
  }
}

ChptFmtNative format (also CHPT_FMT_NATIVE)

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