amded.t2t

AMDED

July, 2019

%!target: man


= NAME =
amded - Basic command line tagging engine for audio files


= SYNOPSIS =
//amded// **OPTION(s)**... **FILE(s)**...


= DESCRIPTION =
//Amded// is based on KDE's taglib. It is a very basic program, that
lists and modifies meta information found in audio files.

//Amded// is **not** an automatic tagging utility. But it can be used
as a tagging backend in higher-level applications.

//Amded// currently supports the following file types:

- Ogg Vorbis
- FLAC
- mp3 (id3v2, id3v1 and apetag support)
- mp4
- opus


= OPTIONS =
: **-h**
Display a short usage message.

: **-V**
Display version information.

: **-L**
Display amded's licencing information.

: **-l**
List the tags in the given files in a human readable form.

: **-m**
List the tags in the given files in a machine readable form. By default, string
type payload is base64 encoded in this mode. See the //machine-dont-use-base64//
option about changing this default behaviour.

: **-j**
List the tags in the given files in the JSON format. By default, string type
payload is base64 encoded in this mode. See the //json-dont-use-base64//
option about changing this default behaviour.

: **-S**
Strip all tags from a file. With files, that support multiple tag
implementations to be present (like mp3 files) the write-map is used. For
example, the strip id3v1 tags from a file: "amded -W mp3=id3v1 -S foo.mp3"

: **-s** //<aspect>//
Produce a list of supported aspects. Valid aspects are: **tags**,
**file-extensions**

: **-o** //<optional-parameter(s)>//
Pass a comma-separated list of optional parameters into //amded//. See
//OPTIONAL PARAMETERS// below for details.

: **-R** //<readmap(s)>//
Configure how tags are read from certain file types. See //Read Maps//
below.

: **-W** //<writemap(s)>//
Configure how tags are written to certain file types. See //Write Maps//
below.

: **-t** //<tag>=<value>//
Sets a **<tag>** to a **<value>**. This option can be used multiple times
for different tags.

: **-d** //<tag>//
This is a special form of **-t**: But instead of modifying the tag's value, it
is removed entirely. This may be used alongside **-t**.


= OPTIONAL PARAMETERS =
The **-o** option allows the following parameters to be passed to //amded//:

- //json-dont-use-base64//: When JSON output is used (the **-j** option),
  do **NOT** use base64 to encode string payload.
- //machine-dont-use-base64//: Like //json-dont-use-base64//, but used with
  machine readable output (the **-m** option).
- //keep-unsupported//: When stripping tags, also remove tags, that are
  unsupported by TagLib's "PropertyMap" abstraction.
- //show-empty//: Print supported tags with empty values.


= LISTING ACTIONS =
//Amded// supports two ways of listing meta information from audio files:
**human** readable, **machine** readable and **json** serialised.

Note that the listing output will include more information than the ones
//amded// will let you modify. For example it will include information
like the **samplerate** in use in the file or the **length** in seconds.


== Human Readable Format ==
This format is supposed to make it easy for the human eye to read
through the listing of meta information gathered from the file in
question.

The format will look like this:

  <filename>
  tagname0    | tagvalue0
  tagname1    | tagvalue1
  [...]
  tagnameN    | tagvalueN

So an example listing may look like this:

  <Bit Shifter - Hexadecimal Genome.mp3>
  file-type    | mp3
  tag-types    | apetag,id3v2
  tag-type     | apetag
  artist       | "Bit Shifter"
  album        | "Information Chase"
  track-number | 3
  track-title  | "Hexadecimal Genome"
  year         | 2006
  genre        | "Electronic"
  is-va        | false
  bit-rate     | 192000
  sample-rate  | 44100
  channels     | 2
  length       | 199

This form of output is requested by the **-l** command line option.


== Machine Readable Format ==

As opposed to the earlier described human readable format, this output
style is supposed to make it easy for machines to read and split up into
**<tag>**=**<value>** pairs, associated to filenames.

To achieve that, this output format uses three ASCII control characters.
Namely:
: **EOT**
//End-of-Transmission//, used to seperate data for different files from
one another. This byte's hex value is **0x04**.

: **ETX**
//End-of-Text//, used to seperate different **<tag>**=**<value>** pairs
from each other. The hex value of the byte is **0x03**.

: **STX**
//Start-of-Text//. **<tag>** and **<value>** pairs are not actually
seperated from each other by the use of an equal sign, but really by the
//STX// byte. That prevents the equal sign from having a special meaning
in this output format. The hex value of the byte is **0x02**.


By default, every piece of string-type payload is transmitted using base64
encoding, with the payload ending in a ASCII line feed (**0x0a**) character. No
other piece of payload contains line feed characters. The
//machine-dont-use-base64// option can be used insert strings unencoded. Note,
that it is unsafe to use unencoded payload, because the payload might contain
one of the control characters used by the machine-readable output protocol,
thus breaking consistent parsing.

An example output could look like this (the example assumes the
//machine-dont-use-base64// option is set, for better //human// readability in
this manual):

  file-name**<STX>**One.mp3**<ETX>**artist**<STX>**Someone**<EOT>**file-name**<STX>**Two.mp3**<ETX>**artist**<STX>**SomeoneElse

This form of output is requested by the **-m** command line option. And
example parsers for this output method are included in the //amded//
distribution (the process-m.* files, to be precise).


== JSON Serialised Format ==

This output mode, produces a string conforming to the JSON data interchange
format (see http://www.json.org for details). All string-content is base64
encoded by default (see the //json-dont-use-base64// option about this).


= FILE TYPE SPECIFIC BEHAVIOUR =

== mp3 ==
In listing modes, //amded// includes a pseudo tag called **tag-types**, of
which the value is a comma seperated list of tag types found in the file. Valid
tag types are: **id3v1**, **id3v2** and **apetag**.

It will also display a pseudo tag called **tag-type**, which will indicate from
which tag the presented data was gathered from. Valid values are the same as
for the **tag-types** pseudo tag.


= MAPPING =

For some file types (currently only //mp3//) more than one type of tag
is allowed at the same time. This fact requires //amded// to have a way
of determining which tag types to **write** for a given file type and
from which type to **read**. Setting this up is what we call //mapping//
tagtypes to file types.


== Read Maps ==
Read maps configure which tags get which priority when reading.

A read map looks like this:

  <file-type>=<tag-type-A>,<tag-type-B>,...

So, for //mp3// it may look like this:

  mp3=apetag,id3v2

Read maps are set up using the //-R// command line switch. Multiple read
maps can be configured, by concatenating them one after another, separated
by a single colon (**:**).

Read maps are a serial concept with a first come first serve paradigm.
That means, that meta information is read from exactly **one** tag type.
If, for example, in the example above an **apetag** exists, the information
is read from the **apetag** and //only// from it. No other tag will be
considered once a tag type with higher priority was found.


== Write Maps ==
Write maps configure which tag types are written to files. Syntactically,
write maps look like read maps (see above). However, there is a conceptual
difference: Writing tags can be thought of as a parallel process. Unlike
**reading** tags, when **writing** tags **all** types defined in a write
map are written and **no** guarantees as to which tag is written first are
made.


= SEE ALSO =
Taglib: <http://taglib.github.io>


= COPYRIGHT =
Copyright (c) 2009-2019 amded workers, All rights reserved.
Terms for redistribution and use can be found in the LICENCE file.