Skip to main content

Introduction

kantag is a set of Python libraries and tools for managing audio file (flac, ogg vorbis, mp3, and m4a) metadata using external text files called “kantag files”. The format of the file is identical regardless of audio file type. Included is a tool to generate the text file from existing tags, path, and MusicBrainz data, initkan; a tool to write the metadata to the audio file tags, applykan; and a tool to display metadata, showkan. A typical kantag file would have lines that look like like this:

# Album / common track info
a AlbumArtist=Rush
a AlbumArtistSort=Rush
a Album=2112
a Date=1976-03-12

a Composer=Geddy Lee
a ComposerSort=Lee, Geddy
t 01-05 Composer=Alex Lifeson
t 01-05 ComposerSort=Lifeson, Alex
t 01-03,06 Lyricist=Neil Peart
t 01-03,06 LyricistSort=Peart, Neil

t 01 Title=2112
t 01 Work=2112
t 01 Part=1. Overture
t 01 Part=2. The Temples of Syrinx
t 01 Part=3. Discovery
t 01 Part=4. Presentation
t 01 Part=5. Oracle: The Dream
t 01 Part=6. Soliloquy
t 01 Part=7. Grand Finale

Typical Usage

In a typical kantag workflow, the user will have an album of audio files, whether ripped from a CD, purchased from an online store, downloaded from Bandcamp, or another source. In most cases, the files will already contain metadata tags. MusicBrainz Picard is a recommended choice for setting the initial metadata, especially for files ripped from physical media. The tool initkan will produce a baseline file for a set of audio files:

$ initkan -v -b=y -M=y *.ogg > tags.kan

The output would typically be retained as a file in the same folder as the audio files, as in the above example. Then, the file can be edited by any available text editor, to meet the user’s personal tastes. Note, there are additional tags recognized by the kantag tools that are not necessarily output by initkan. To write the tags back to the audio files, use applykan:

$ applykan -v tags.kan *.ogg

Installation

Warning

Some Linux distributions discourage installation of system-level python packages using pip or setup.py install, due to collisions with the system package manager. In those cases, dependencies should be installed through the package manager, if possible, or choose a user folder installation method.

Installing with pip

If your system has pip installed, and you have access to install software in the system packages, then kantag kan be installed as administrator from PyPI:

# pip install kantag

If you do not have access to install system packages, or do not wish to install in the system location, it can be installed in a user folder:

$ pip install --user kantag

Installing from source

Either download a release tarball from the Releases page, and unpack:

$ tar zxvf kantag-1.1.0.tar.gz

Or get the latest source from the git repository:

$ git clone https://github.com/dgasaway/kantag.git

If you have access to install software in the system packages, then it can be installed as administrator:

# python setup.py install

If you do not have access to install system packages, or do not wish to install in the system location, it can be installed in a user folder:

$ python setup.py install --user

File Format

Overall, if the kantag file contains any non-ASCII characters, it should be UTF-8 encoded without BOM. Each line is parsed according to the rules below. Blank lines are allowed and ignored.

Line format

The first character of a line indicates the line type:

Char

Description

#

A comment line that will be ignored.

a

A tag that will be applied to all files.

d

A tag that will be applied to selected discs.

t

A tag that will be applied to selected tracks.

For disc and track types, next is a space followed by a list of disc/track numbers to which the tag applies. The list is comma separated and may contain ranges indicated by a hyphen. Some examples:

Selector

Description

t 10

Applies to track 10.

d 2

Applies to all tracks on disc 2.

d 1-3

Applies to all tracks on discs 1, 2, and 3.

t 01,05-07,10

Applies to tracks 1, 5, 6, 7, and 10.

The numbers may need to be zero padded as in the above track example if the audio filename has the disc or track number zero padded. This can also depend on the setting the --path-regex option passed to applykan. With default settings, track numbers should be padded to two digits in the kantag file and in filenames. In addition, when working with a multi-disc release, track numbers should be prepended with the disc number, as in these examples:

Selector

Description

t 101-103

Applies to tracks 1 to 3 of disc 1.

t 105,201-202

Applies to track 5 of disc 1, and tracks 1 and 2 of disc 2.

Next comes a space and the tag name/value pair separated by an equal sign. Anything before the first equal sign will be used as the tag name, anything after and to the end of the line is the value. Putting it all together, you have something like this:

t 07 Composer=Jaromír Weinberger

There is no support for multi-line values. Instead, use multiple instances of the tag:

t 07 Comment=Work premièred in 1927.
t 07 Comment=Known in English as "Švanda the Bagpiper" or "Schwanda the Bagpiper".

Metadata

Release files for kantag 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kantag 2.0.0
File Size Uploaded Provenance Actions
kantag-2.0.0.tar.gz 51.4 kB Without provenance Details for kantag-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kantag 2.0.0
File Interpreter ABI Platform Actions
kantag-2.0.0-py3-none-any.whl Python 3 none any Details for kantag-2.0.0-py3-none-any.whl

Total release size: 107.2 kB

Release files / kantag-2.0.0.tar.gz

Download URL kantag-2.0.0.tar.gz
Size 51.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a8cc69ce0921d22ccdb960a598cb069bc8d77cfd1c7447a24b5905d759779ae9
BLAKE2b-256 checksum
How to use checksums
77e9f7dea15ce25eca26b215b43edb3137e8aa5e5e78c372faaa6115ee6a1f96
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.55.2 CPython/3.7.9

Release files / kantag-2.0.0-py3-none-any.whl

Download URL kantag-2.0.0-py3-none-any.whl
Size 55.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ff29cb0b0c6dfaed9bc109262382d14a432d20ce175403b614c2eeaddc3ad95c
BLAKE2b-256 checksum
How to use checksums
50875238a73692e95ddba98436934d9990af4ee89800fd38d3ca014a438ca0e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.55.2 CPython/3.7.9

Security for kantag 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page