Taggit Metadata Editor User’s Guide

Table of Contents

Next:   [Contents][Index]

Audio Metadata Editor (taggit)

Copyright © 2016-2020 Mahlon R. Smith, The Software Samurai This manual describes version 0.0.08 of ’taggit’. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
'taggit' is a metadata (tag data) editor for audio files. ’taggit’ supports editing of tag data for a single file or for an entire album in a single operation.


Next: , Previous: , Up: Top   [Contents][Index]

Introduction

Why choose Taggit?

Taggit (taggit) is a simple, console (terminal) dialog application which allows simultaneous editing of tag data for multiple audio files.

While most tag editors target a single audio file, Taggit allows editing of an entire album (up to 99 source files) as a single, integrated operation.

Taggit DOES NOT access online music databases to automatically fill in the tag fields. Several other tag editors are available for Linux/UNIX, some of which can access the online databases for tag information, perform playback of the audio file, and support many more audio formats. If your primary focus is simply to create tag data for your audio files, we recommend:

VLC Media Player (excellent audio/video player, but marginal tag editing) puddletag (overall, very good but not well supported) MP3Tag (easy to use, but for Windoze only) MusicBrainz Picard (tightly integrated with the MusicBrainz database)

Each of these applications has its strengths and weaknesses. The primary weaknesses are:

  a) only a casual adherence to the established standards,   b) support for only a small subset of the defined tag fields   c) reliance on third-party decoding libraries   d) a generally amateurish approach to software design   e) unbelievably poor documentation

Each of these weaknesses is a major no-no in an engineering classroom, and except for third-party libraries, a professionally-designed application should never exhibit these characteristics.

Taggit is designed specifically as a teaching tool for the software-design student who wants to create a software application with a user-friendly, multilingual user interface.

As such, a general user may find Taggit to be rather primitive; however, software engineering students may benefit from the simple, C++ coding style, the algorithms for multilingual support and the source code’s extensive internal documentation.

The current release of Taggit supports three audio formats and four user-interface languages: MP3 for better or worse, the audio industry standard OGG/Vorbis the next generation of open-standards audio WMA Windows(tm) Media Audio (ASF media container) Spanish Mexican (Califas-style) Spanish is used. Chinese (simplified) This is the official character set used on the mainland Vietnamese Modern, six-tone South/Central Vietnamese is used English U.S. English, perhaps with a few British/Aussie influences

The supported languages were selected simply because they are the languages the author knows. These are all LTR (left-to-right) languages.

The plan for the next major release is that it will include support for one of the RTL (right-to-left) languages. All the hooks are in place and have been tested with simulated data. However, our Yiddish is of the Brooklyn street variety, and our attempts at learning Arabic have been a humiliating failure. :(

Please see RTL language support for additional information on RTL user-interface languages.





Next: , Previous: , Up: Top   [Contents][Index]

Operational Overview

Taggit (taggit) is a simple, console (terminal-window) application which allows simultaneous editing of tag data for multiple audio files.

Taggit is implemented as a dialog using the NcDialog API written by the same author (see by the same author). This API is based on the standard 'ncursesw' library included with all GNU/Linux distributions.


The screenshots below are of a 30x132 window which has been compressed to fit within the width of this document.

┌─────────────────────────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──────────────────────┐ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigate: ↑↓←→ mouse wheel │ File Edit View Help Edit: Press SPACE key or │ Save All Modified Data ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Click on target field │ ╞════════════════════════════╤════════════════════════════════════▅▅▅▅══════════════════════════════════╡ │ F M File Name ▼ │ Title Artist Album │ Track 01.mp3 Apple Sauce Creempuff Girls Can't Drive Ho ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Track 02.mp3 Wane Manner Creempuff Girls Can't Drive Ho │ │ │ Track 03.mp3 Greenbryer Steakhouse Creempuff Girls Can't Drive Ho │ │ │ Track 04.mp3 Chatty Cathy Creempuff Girls Can't Drive Ho │ │ │ Track 05.mp3 Tarnished Love Creempuff Girls Can't Drive Ho │ │ │ Track 06.mp3 Ham and Eggs On Toast Creempuff Girls Can't Drive Ho Track 07.mp3 Tommie's Ho Creempuff Girls Can't Drive Ho │ │ │ Track 08.mp3 Friends At Last Creempuff Girls Can't Drive Ho │ │ │ Track 09.mp3 Tiny Tim's First Lay Creempuff Girls Can't Drive Ho │ │ │ Track 10.mp3 Can't Drive Home Alone Tonight Creempuff Girls Can't Drive Ho │ │ │ Track 11.mp3 Roger Rabbit Gets Funky Creempuff Girls Can't Drive Ho │ │ │ └────────────────────────────┴────────────────────────────────────▅▅▅▅──────────────────────────────────┘

┌─────────────────────────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──────────────────────┐ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ 导航 : ↑↓←→ 要不然 鼠标滚轮       文件 修正 查看 帮助      编辑    : 按空格键 要不然  保存所有修改的数据 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ 单击目标字段       ╞════════════════════════════╤════════════════════════════════════▅▅▅▅══════════════════════════════════╡ │ F M 文件名 ▼       │ 歌名 艺术家 专辑               Track 01.mp3 Apple Sauce Creempuff Girls Can't Drive Ho ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Track 02.mp3 Wane Manner Creempuff Girls Can't Drive Ho │ │ │ Track 03.mp3 Greenbryer Steakhouse Creempuff Girls Can't Drive Ho │ │ │ Track 04.mp3 Chatty Cathy Creempuff Girls Can't Drive Ho │ │ │ Track 05.mp3 Tarnished Love Creempuff Girls Can't Drive Ho │ │ │ Track 06.mp3 Ham and Eggs On Toast Creempuff Girls Can't Drive Ho Track 07.mp3 Tommie's Ho Creempuff Girls Can't Drive Ho │ │ │ Track 08.mp3 Friends At Last Creempuff Girls Can't Drive Ho │ │ │ Track 09.mp3 Tiny Tim's First Lay Creempuff Girls Can't Drive Ho │ │ │ Track 10.mp3 Can't Drive Home Alone Tonight Creempuff Girls Can't Drive Ho │ │ │ Track 11.mp3 Roger Rabbit Gets Funky Creempuff Girls Can't Drive Ho │ │ │ └────────────────────────────┴────────────────────────────────────▅▅▅▅──────────────────────────────────┘


Technical Details of Metadata formatting

Please see Tech Notes for a description of the Metadata (tag) structure for each supported audio format.




Next: , Previous: , Up: Top   [Contents][Index]

Invoking

Summary of Options

  OPTION  DESCRIPTION
  'a' option Enable all tag fields
  'c' option Application color scheme
  'C' option Specify alternate      configuration file
  'd' option Specify source directory
  'D' option Dump metadata to a plain text  file
  'f' option Source filename(s)
  'F' option File containing list of     source filenames
  'i' option Ignore (discard) any existing  metadata from files
  'I' option Insert an image into each  target file
  'l' option Language for user interface
  'L' option Locale specification  (default: system settings)
  'm' option Enable/disable mouse support  (enabled by default)
  'p' option Pause to display startup  diagnostics
  'P' option Preserve source files: write  output to alternate filename
  'h' option Display a list of all Taggit  options (short form)
  's' option Sort options for data display  (default: by filename)
  'album' option Album name (for all source  files)
  'artist' option Artist(s) (for all source  files)
  'help' option Display a list of Taggit  command-line options
  'version' option Reports the Taggit version  number and copyright info

Usage

taggit [OPTIONS]

Options may be specified in any order.
Short-form options without arguments may be combined into a single token.

For options which require arguments, the option must either be joined to its argument using the EQUAL sign (’=’):
-option=argument
or the argument must be the next token on the command line:
-option argument
(A “token” is a character sequence, delimited by spaces.)

If the argument string contains space characters, it must be enclosed in either single-quotes ( ' ) or double-quotes ( " ).
-option='arg u ment'
-f="She's a Woman.oga"

If Taggit is invoked without options, it is equivalent to invoking as:
   taggit -d=.
indicating that Taggit should scan for all media files in the current directory.

Examples:
   taggit -f=Track01.mp3,Track02.mp3,Track03.oga

   taggit -d='Bon Jovi/Slippery When Wet' --album='Slippery When Wet'

   taggit -aiPs=Title --artist Foreigner --album 'Jukebox Hero'

Using an option more than once is strongly discouraged.
If multiple instances of an option appear in the Taggit invocation, then the second and subsequent instances may produce unexpected results.


Note on Filenames: Filenames for music files often contain odd characters seldom seen elsewhere, but which are in keeping with the tone or mood of the music itself. For example, “Ridin’.oga” by Rascal Flatts which uses the single-quote character, or “Will You Be There (In the Morning).oga” by Heart which uses parentheses. Some of these characters can cause problems with various system functions and utilities. For this reason, we scan all path/filename strings for these“special” characters and encapsulate them so the system will process them as ordinary characters, and not interpret them as special commands. The more common of these are:
( ) & | ; < > ? " and ' (single-quote)
Although under Linux, all printing characters are technically valid filename characters, certain characters should NEVER be used as filename characters. These include: $ { } * and ` (back-tick).

Author’s Note: Command-line options are implemented in English only, and the switch characters have been selected based on the English words describing the action. We experimented with command-line options in multiple languages, however, the ambiguity and parsing conflicts encountered make multilingual command switches impractical.


Options

–a Enable display of all tag-data fields.

Enable all tag fields for display and editing.

It is customary to disable little-used or redundant fields to create a simpler user interface, but some audio files will have data in these uncommon fields.

By default, the settings in the configuration file determine which tag fields will be displayed, but the '-a' option can be used to override the configuration settings and to display all defined fields.

Please see Configuration for more information.

Invocation Examples

taggit -a




–c=COLOR Select a color scheme for the application dialog.

The Taggit application is implemented as a dialog window. The colors used for this dialog, its contents, and the various sub-dialogs may be specified by selecting the desired color scheme.

The available options are:

'black' 'red' 'green' 'brown' 'blue' 'magenta' 'cyan' 'gray' 'default'

The default color scheme uses a basic white text on a cyan background, with high-contrast colors for the dialog’s contents and interface controls.

Other color schemes use the background color specified (whenever practical). Actual functionality is identical for all color schemes, so choose the color scheme that you find most pleasing.

The color scheme may be changed from within the application using the Set Color Scheme option in the ‘View’ menu.

The color scheme may also be specified in the configuration file.
Please see Configuration for details.

Invocation Examples

taggit -c=blue taggit -c magenta




–C=FILESPEC Specify an alternate configuration file.

The default configuration file is 'Taggit.cfg' and is located in the same directory as the application binary (program file).

The default configuration file may be edited to provide the most-often-needed setup parameters.

An alternate configuration file may be specified for special circumstances, or to provide personalized setting when multiple users share the same system.

To create an alternate configuration file, simply copy the default configuration file to a convenient location and make the desired modifications to its parameters.
Please see Configuration for details.

Invocation Examples

taggit -C=Taggit_Classical_Music.cfg taggit -C grunge.cfg taggit -C="~/Music/Kid’s Piano Recitals/Recitals.cfg"




–d=PATH Specify the source directory.

If no source files are specified by either the '-f' option or the '-F' option, then by default, the application scans the current-working-directory (CWD) on startup. An alternate source directory for the scan may be specified using the '-d' option.

The application will scan the specified directory for all audio files. All files with supported audio formats will be included as source files.

Invocation Examples

taggit -d=’~/Music/Elton John/Rock of the Westies’ taggit =d ’./Victim of Love’

Important Note:

  1. When source files are specified using the 'd' option, the application will not scan the current working directory (CWD) for additional source files.
  2. The 'd' option may be used in conjunction with the 'f' option.
  3. Note that the 'd' and 'F' options are mutually exclusive. If both are specified, only the first will be accepted.
  4. Duplicate Filenames
    Keep in mind that duplication of source file specifications is not allowed. (See duplicate filenames.)

See also:
   'f' option and
   'F' option





–D Dump (copy) metadata to a plain-text file.

Use the 'D'ump option to simply make a copy of the tag data from one or more audio files. The source files are not modified in any way, and the data obtained are written to a plain text file.

When invoked with the 'D' option, the application dialog does not open. The application simply reads the tag data from the specified files and then exits. Thus, the only other options which are recognized in conjunction with the 'D' option will be the source file specification options:

'f' option specify individual files 'F' option specify a file containing source filenames 'd' option directory to scan for source files
If none of these are specified, the current-working-directory will be scanned for audio source files.

On completion, a message will be written to the console indicating the location of the target file.

Invocation Examples

taggit -D taggit -Dd=’Foghat/Rock and Roll Outlaws’ taggit -Df=’Blue Spruce Woman’

Example Output

# Metadata Summary - 2017-01-19T06:53:25 (Taggit)
------------------------------------------------------------

# Blue Spruce Woman.mp3
  Title ------------------------ Blue Spruce Woman
  Artist ----------------------- Foghat
  Album ------------------------ Rock and Roll Outlaws
  Track ------------------------  7
  Year ------------------------- 1974
  Genre ------------------------ (17) Rock
  Record Label, Publisher ------ Bearsville
  Composer(s) ------------------ Dave Anderson
  Playback Time (mSec) --------- 248121
  

Summary data may also be obtained from within the application:
see Save Tag Summary, in the 'File' menu, or
see View Tag Summary, in the 'View' menu.





–f=FILESPEC[,...] Specify a sequence of of source filenames.

Specify one or more source filenames, separated by commas.

If used, this option must include at least one source filename.

A source filename may be specified in several ways.

Invocation Examples

taggit -f=’Honky Cat.oga,Rocket Man.oga,Mona Lisas and Mad Hatters.oga’

Important Note:

  1. When source files are specified using the 'f' option, the application will not scan the directory for additional source files.
  2. The 'f' option may be used in conjunction with either the 'd' or 'F' options.
  3. Duplicate Filenames
    Note that the application scans for duplication of source file specifications and removes the duplicate source records from the list. This is necessary in order to avoid potential loss of data.

    Duplicate filenames that refer to different source files are not affected by this scan.


See also:
   'F' option and
   'd' option





–F=FILESPEC Specify a file containing the filename list.

As a convenience, the list of source filenames may be specified by a plain-text file, one filename per line. For instance, you could capture a list of all MP3 files in a certain directory.

cd 'Lady Samantha' echo '#Lady Samantha Tracks' 1>filelist.txt ls -1 *.mp3 1>>filelist.txt

This would result in a text file containing the following:

#Lady Samantha Tracks Rock n' Roll Madonna.mp3 Whenever You're Ready.mp3 Bad Side of the Moon.mp3 Jack Rabbit.mp3 Into the Old Man's Shoes.mp3 It's Me That You Need.mp3 Ho! Ho! Ho!.mp3 Skyline Pigeon.mp3 Screw You.mp3 Just Like Strange Rain.mp3 Grey Seal.mp3 Honey Roll.mp3 Lady Samantha.mp3 Friends.mp3

Note that lines in the file beginning with the hash character ('#'), and blank lines will be ignored by the application.

Invoke the application using the file just created:

Invocation Examples

taggit -F filelist.txt taggit -F=’./Lady Samantha/filelist.txt’

Important Note:

  1. When source files are specified using the 'F' option, the application will not scan the directory for additional source files.
  2. The 'F' option may be used in conjunction with the 'f' option.
  3. Note that the 'F' and 'd' options are mutually exclusive. If both are specified, only the first will be accepted.
  4. Duplicate Filenames
    Keep in mind that duplication of source file specifications is not allowed. (See duplicate filenames.)

See also:
   'f' option and
   'd' option





–i Ignore existing metadata.

The 'i'gnore option is used to ignore (discard) any existing text-tag data and embedded images in the source files. All tag fields will be displayed as empty, and if the file is saved, the existing text-tag data will be removed. (Non-text tags will be saved unmodified.)

The tag fields may also be cleared through the Edit Menu, using the 'Clear File Metadata' or 'Clear All Metadata' options.

Invocation Examples

taggit -i taggit -id=’Coldplay/A Rush of Blood to the Head’ taggit -i -f=Clocks




–I Insert external image.

Specify an external image file to be embedded into one or more audio files.

The image file specified will be displayed when the “Insert Image” dialog is invoked. This dialog is used to set the parameters for embedding an image tag into the target audio file(s). When an image file is specified using the -I option, this dialog will open automatically on application startup. The dialog may also be invoked directly:

Please see Add Image File item of the Edit Menu.
Please see the ALT+CTRL+I shortcut key under see Navigation.

Note that the metadata specification allows for a URL (Universal Resource Locator) to be embedded in the audio file instead of embedding the image itself. This URL would reference an image located outsize the audio file. However, Taggit does not suport external image references at this time.

Invocation Examples

taggit -I=’~/Music/Coldplay/Rush-of-Blood-to-the-Head.png’ taggit -I ’./Rush-of-Blood-to-the-Head.png’

To review the images which are embedded into the audio file, please see view image data menu item.





–l=LANGUAGE Specify the user interface language.

Specify the language for the user interface.

By default, the user interface language is determined by the locale set in the terminal program’s environment. If your system is configured for an unsupported language, the user interface will default to English.

Use the 'l' option to specify a non-default user interface language. Taggit currently supports the following languages.

Invocation Examples

To specify the language, only the first two characters of the language name are necessary. In general, the first two characters of the language correspond to the ISO-639-1 language definition: Español (es), Zhōngwén (zh), English (en), Tiếng Việt (vi, ‘ti’ is also recognized). Argument is not case sensitive.

taggit -l=Zhongwen taggit -l ZH taggit -L=zh_CN.utf8 -l=Zh

Note that the system’s locale must support UTF-8 character encoding in order to fully display the character set of the target language. For additional information on the system locale, see 'L' option below.





–L=LOCALE Specify the locale for output encoding.

The system locale provides information on how text input and output will be interpreted and displayed.

The locale specifies not only the primary user interface language, but also the character encoding used, the format for time, currency, numeric formats, units of measurement and more.

Most, if not all modern GNU/Linux distributions default to a locale which uses UTF-8 character encoding so that all characters in all languages may be displayed.

The Taggit application will scan the terminal environent for the system default locale, and if found will use the specified language and text formatting by default. Therefore it is usually unnecessary to directly specify a locale. If, however the displayed text is not formatted correctly or if unexpected characters are mixed with the data, then it is likely that you will need to specify the locale to be used.

To determine the locale used by your system, open a terminal window and type the following command:

locale -v (ENTER)

For United States English, something like the following will be displayed.

[Taggit]$ locale -v LANG=en_US.utf8 LC_CTYPE="en_US.utf8" LC_NUMERIC="en_US.utf8" LC_TIME="en_US.utf8" LC_COLLATE="en_US.utf8" LC_MONETARY="en_US.utf8" LC_MESSAGES="en_US.utf8" LC_PAPER="en_US.utf8" LC_NAME="en_US.utf8" LC_ADDRESS="en_US.utf8" LC_TELEPHONE="en_US.utf8" LC_MEASUREMENT="en_US.utf8" LC_IDENTIFICATION="en_US.utf8" LC_ALL=

It can be seen that the locale is set to en_US.utf8.
The language is (usually) specified by either the two-character code according to the ISO-639-1 standard (Example: en), or the three-character code according to the ISO-639-2 standard.
The country is specified as a two-character code according to the ISO-3166-2 standard (Example: US)

Non-UTF-8 locales may be named in semi-random ways, but should be avoided as much as possible.

To list all the locales available on your system type the following command:

locale -a (ENTER)

Any locale which supports UTF-8 encoding may be specified for use with the Taggit application.

locale -a | grep -i 'utf8' (ENTER)

The locale may be specified alone or in conjunction with a language specification.

Invocation Examples

Note that because locale names are actually filenames, the argument IS case sensitive.

taggit -L=zh_CN.utf8 taggit -L vi_VN.utl8 taggit -L=es_MX.utf8 -l=Es




–m=OPTION Enable or Disable Mouse Support.

The Taggit user interface is designed primarily for the mouse. While all functionality is available through the keyboard alone, for most operations the mouse interface is more intuitive and fluid.

For this reason, mouse support is enabled by default.
The mouse interface can also be enabled/disabled in the configuration file (see Configuration).

Use the 'm' option to enable or disable mouse support for the current session.

Invocation Examples

taggit -m=disable taggit -m enable

Mouse support for a console program is subject to many technical issues. Therefore, Taggit requires a mouse with at least one button AND a scroll wheel. If your mouse does not have a scroll wheel (or scroll-wheel emulation), then mouse support cannot be enabled.

Please see User Interface for more information.





–p[v] Pause on Startup.

This option may be used to pause briefly during the startup sequence so that the startup diagnostic messages can be read.

The application writes certain diagnostic data to the console window during the startup sequence which is immediately overwritten when the application dialog opens. The 'p' option inserts a small delay (approximately four(4) seconds) between completion of the startup sequence and opening the application dialog.

This is useful if the application encounters memory allocation errors, file access errors, detection of an unsupported language or locale, or other system configuration problems.

The 'p' option also has a ‘verbose’ sub-option which will display much more information — specifically it will display the value for each entry in the configuration file — and will then wait for a keypress before opening the application dialog. While verbose diagnostics are used primarily during application development, they are also useful for identification of syntax or other errors in the configuration file.

Invocation Examples

taggit -p (4-second pause) taggit -pv (verbose diagnostics)





–P Preserve the original source file.

Use the '-P' option to preserve an unmodified copy of the original audio source file(s).

By default, the application writes the edited metadata directly to the source file. The '-P' option will save the original source file as a backup file and write the edited metadata to a copy of the source file.

Note that under GNU/Linux a backup file is indicated by adding a tilde '~' character to the end of the filename.

For instance, if you edit the metadata for the song "Bad Romance" by Lady Gaga, the result will be two files:

Bad Romance.mp3 File with edited metadata Bad Romance.mp3~ Original source file

The option to preserve the original source files is also available in the “Save Metadata to Target” dialog.
Please see File Menu for more information on save options.

Of course this option requires more storage space than simply modifying the source file directly, so when you are sure that the edited files are satisfactory, the backup files may be deleted.

Invocation Examples

taggit -P




–s=FIELD Sort the file list according to the specified display field.

The list of source files and their tag data will be sorted alphabetically, using the text in the specifield display field.

By default, the list is sorted, low-to-high, on the filename field; however, the list may be sorted (low-to-high) on any of the following fields.

Filename sort by name of source file (default) Title sort by song title Track sort by track number Album sort by album name Artist sort by artist name(s) None no sort, display in the order files are stored on the disc

The sort order may be set from within the application using the ‘Sort File List’ item in the ‘View’ menu.
Please see Sort-by Submenu for more information.

The default field on which to sort may also be specified in the configuration file.
Please see Configuration for details.

Invocation Examples

taggit -s=Track taggit -s Artist

Note that if one or more source files contains no data in the selected sort-by field, then those files will be grouped at the top of the list.





–h Display Taggit command-line help.

This is the short form of the 'help' option, below.

Invocation Examples

taggit -h




––album=ALBUM Specify the "Album" field for all files.

The ‘--album’ option is used to automatically set the ‘Album’ field for all source files to the specified value. This is useful when all files being edited are from the same album.

The ‘Album’ field (or any field) may also be duplicated to all source files using the ‘Duplicate Field’ option in the ‘Edit’ menu.
Please see Edit Menu for details.

Invocation Examples

taggit --album="Life in a Beautiful Light" taggit --album ’One Foot in the Blues’




––artist=ARTISTS Specify the "Artists" field for all files.

The ‘--artist’ option is used to automatically set the ‘Artists’ field for all source files to the specified value. This is useful when all files being edited are by the same artist.

The ‘Artists’ field (or any field) may also be duplicated to all source files using the ‘Duplicate Field’ option in the ‘Edit’ menu.
Please see Edit Menu for details.

Invocation Examples

taggit --artist="Amy Macdonald" taggit --artist ’ZZ Top’




––help Display Taggit command-line help.

Command-line Help. Display a brief summary of command-line usage and options. (overrides everything on command line except '--version')

Invocation Examples

taggit --help

Also see 'h' option, for short-form help option.





––version Report Taggit version number.

Display the Taggit version number and copyright information. (overrides everything else on command line)

Invocation Examples

taggit --version



Next: , Previous: , Up: Top   [Contents][Index]

User Interface




Next: , Up: User Interface   [Contents][Index]

User Interface Basics




Next: , Up: User Interface Basics   [Contents][Index]

Application Layout

Taggit is a console (terminal window) application which presents tag data and user interface controls as a text-based dialog window.

The dialog is made up of three(3) sub-dialogs which are simultaneously displayed within the parent window.

  1. User Interface Controls window

    This window is at the top of the application dialog and extends the full width of the dialog.

    The user interface controls including the Menu Bar and the ‘Save All’ pushbutton are contained in this window.

    This window also contains a “Quick Help” message; a simple reminder of how to navigate the application and how to access the edit fields.

  2. Filename Window

    The Filename window is on the left side of the dialog and below the UI Controls window.

    The name and the displayed metadata for the file with input focus is underlined in RED. This is the file which will be edited when the data editing sub-dialogs are invoked.

    (For the Red color scheme this underline is in a contrasting color.)

    For each file displayed, this window contains three(3) items.

    • Filename change indicator

      This indicator is located in the column labelled with an 'F' for 'F'ilename.

      For the default application color scheme, this indicator is Green if there are no changes to the filename pending, and it is Red if the filename has been edited but the name of the file has not yet been updated.

      (For other color schemes, the indicator colors are modified to contrast with the dialog background.)

    • Metadata changes indicator

      This indicator is located in the column labelled with an 'M' for 'M'etadata.

      For the default application color scheme, this indicator is Green if there are no changes to the metadata (tag data) pending, and it is Red if the metadata have been edited but have not yet been written to the file.

      (For other color schemes, the indicator colors are modified to contrast with the dialog background.)

    • Filename

      This is the full name of the source file as read from the disc.

      The filename can be edited and the file will be renamed when the data are saved.

      Please see Editing the Filename for information of editing the filename.

  3. Metadata (tag data) Window

    The Metadata window is on the right side of the dialog and below the UI Controls window.

    The name and the displayed metadata for the file with input focus is underlined in RED. This is the file which will be edited when the data editing sub-dialogs are invoked.

    (For the Red color scheme this underline is in a contrasting color.)

    The Metadata window displays the data for each active tag field across the width of the window.
    See Activate Fields, for information on selecting the tag fields which will be displayed in the Metadata window.

    The window can be scrolled up and down using:
    — the Up-Arrow and Down-Arrow keys, OR
    — the mouse Scroll Wheel

    Between two and five tag fields can be displayed at any one time (depending on the width of the terminal window). Fields are scrolled horizontally in the Metadata window. To scroll other fields into view, use:
    — the Left-Arrow and Right-Arrow keys, OR
    — the mouse Scroll Wheel in combination with the CTRL key

    Please see Editing the Metadata for information of editing the individual tag-data fields.



This diagram has been compressed to fit within the width of the document.

┌─────────────────────────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──────────────────────┐ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigate: ↑↓←→ mouse wheel │ File Edit View Help Edit: Press SPACE key or │ Save All Modified Data ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Click on target field │ ╞════════════════════════════╤═══════════════════════════════════▅▅▅▅═══════════════════════════════════╡ │ F M File Name ▼ │ Title Artist Album │ Track 01.mp3 Apple Sauce Creempuff Girls Can't Drive Ho │ │ │ Track 02.mp3 Wane Manner Creempuff Girls Can't Drive Ho │ │ │ Track 03.mp3 Greenbryer Steakhouse Creempuff Girls Can't Drive Ho │ │ │ Track 04.mp3 Chatty Cathy Creempuff Girls Can't Drive Ho │ │ │ Track 05.mp3 Tarnished Love Creempuff Girls Can't Drive Ho ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Track 06.mp3 Ham and Eggs On Toast Creempuff Girls Can't Drive Ho Track 07.mp3 Tommie's Ho Creempuff Girls Can't Drive Ho │ │ │ Track 08.mp3 Friends At Last Creempuff Girls Can't Drive Ho │ │ │ Track 09.mp3 Tiny Tim's First Lay Creempuff Girls Can't Drive Ho │ │ │ Track 10.mp3 Can't Drive Home Alone Tonight Creempuff Girls Can't Drive Ho │ │ │ Track 11.mp3 Roger Rabbit Gets Funky Creempuff Girls Can't Drive Ho │ │ │ └────────────────────────────┴───────────────────────────────────▅▅▅▅───────────────────────────────────┘



Next: , Previous: , Up: User Interface Basics   [Contents][Index]

Dialog Dimensions

Taggit opens to the full width and height of the terminal window. If the terminal window is resized, then the application will also be resized to fill the available space.

The application requires that the terminal window be sized to:
      at least 30 rows by 132 columns.
If the terminal window is too small, the application will not open, and an error message will be displayed.

For optimal operation, it is recommended that the terminal window be sized to:
      37 rows by 156 columns or more.




Next: , Previous: , Up: User Interface Basics   [Contents][Index]

Navigation

Navigating through the dialog windows, menus and other application controls is done through the keyboard, the mouse or a combination of the two.

Navigation using the navigation keys

Up Arrow Move the file highlight upward Down Arrow Move the file highlight downward Page-up key Move the file highlight upward by one page Page-down key Move the file highlight downward by one page Home key Move the file highlight to the top of the list End key Move the file highlight to the bottom of the list Left Arrow Scroll the tag fields toward the right CTRL + Left Arrow Scroll the first tag field into view Right Arrow Scroll the tag fields toward the left CTRL + Right Arrow Scroll the last tag field into view ALT+M or ENTER key For the highlighted file, edit the tag field which is at the left side of the Metadata Window ALT+N For the highlighted file, edit the filename.

Navigation using the wheel mouse

Scroll Wheel forward Move the file highlight upward Scroll Wheel backward Move the file highlight downward CTRL + Scroll Wheel forward Scroll the tag fields toward the right CTRL + Scroll Wheel backward Scroll the tag fields toward the left Click Left Mouse Button Edit the field under the mouse pointer OR Access the Menu, Pushbutton or other application control object under the pointer

Hotkeys (shortcuts)

CTRL + S Save edited file ALT + CTRL + S Save edited file with rename CTRL + Q Quit: exit the application ALT + N Edit name of highlighted file ALT + M Edit metadata (tags) of highlighted file ALT + CTRL + I Insert an image into one or more files ALT + CTRL + E Edit setup data for embedded images ALT + I View embedded images for the highlighted file CTRL + A Select all data in the text field under edit CTRL + C Copy selected text data to the clipboard CTRL + X Cut selected text data to the clipboard CTRL + V Paste clipboard data into text field under edit CTRL + Z Undo edits on highlighted file CTRL + D Duplicate contents of field under edit to corresponding field in all files CTRL + T Automatically fill the “Track” field for all files CTRL + R For RTL (right-to-left) user-interface languages only, toggle Textbox data between LTR and RTL display and edit. ALT + UP Shift highlighted file upward in display list ALT + DOWN Shift highlighted file downward in display list



Previous: , Up: User Interface Basics   [Contents][Index]

Dialog Controls

The Taggit user interface is dialog-based. The main application dialog and the various sub-dialogs allow you to interact with the application to issue commands and to modify or retrieve information.

These dialogs use various standard dialog controls such as menus, lists, text-input controls, pushbuttons, radio buttons (on/off switches), spinners and other controls.

Using these controls is straightforward and intuitive, but a brief introduction to each control type may be helpful. The descriptions that follow describe using the keyboard and mouse to access these controls.

Note on “Focus”

The term “focus” refers to the control which will respond when keyboard or mouse input is detected. Focus may be moved among the controls of a dialog by using the TAB and SHIFT+TAB keys or by using the mouse to click on the desired control.


Menu Controls and Lists

Menu controls and List controls are small windows containing a list of items from which you may choose one item. You may choose any one item in the list by scrolling the highlight to that item and pressing the ENTER(RET) key. Scrolling is done either with the arrow keys (up, down, page-up, page-down, home, end), or with the mouse scroll wheel. Alternatively, simply use the mouse to click on the desired item.

Special Keys

— ENTER(RET) key or ’hotkey’ (if defined for the item) 'selects' the item — TAB or SHIFT+TAB key moves to the next/previous control. — For non-menu lists, the highlighted item is 'selected' implicitly. — For menu lists, no selection is made by moving to another control. — Escape key (ESC) leaves the control without making a selection.

In some applications based on the NcDialog API, “hotkeys” may be associated with the individual menu items; however, hotkeys are used only sparingly in the Taggit application because the multilingual user interface makes consistent use of hotkeys impractical.

When an item is selected from a Menu control, the menu will immediately be closed and focus will move to the next control.
Please see Menu Access for descriptions of the individual menus.

For other types of scrolling controls, you may also select an item by scrolling the highlight to that item and pressing the ENTER(RET) key.

In addition, you may select an item by placing the highlight on that item and then moving the focus to the next/previous control.
Again: When the input focus leaves the control, the control’s highlighted item is the ‘selected’ item.

To leave a list control without making a selection, press the ESCAPE key. The highlight will return to its original position, and the focus will be moved to the next control.
Please see Duplicate Fields for an example of a Scrolling list.

Note that a Dropdown list will initially be in a collapsed state and may be expanded either by clicking on it or by using TAB/SHIFT+TAB to highlight the control and then pressing ENTER(RET). When in an expanded state, it behaves like any other scrolling list. When an item is selected, the Dropdown control will return to the collapsed state and focus will be moved to the next control.
Please see Edit Image Stats for an example of a Dropdown list.




Textbox Controls

Text-input controls are used to collect text that you type on the keyboard or to display messages. All Text-input controls have a similar appearance although the text input may be filtered according to the type of information needed.
For instance, some of the text-input filters that may be applied are:
 a) valid filename characters
 b) valid path name characters
 c) valid characters for a URL
 d) alphanumeric data
 e) numeric values
Many other filters may be assigned for specific purposes.

Text may be entered directly from the keyboard or through an Input Method Engine (IME), also known as an Input Method Editor or similar names.

If you enter a character but it does not appear, it is a good indication that the character is not allowed in the current context. Most Textbox controls are also configured to generate an audible alert (beep) if an invalid character is entered. Note that only printing characters (visible characters) may be entered into a Text-input control. Control characters are not allowed.

Depending on the type of data displayed and the language for which the application is configured (LTR or RTL), input is either left-to-right or right-to-left. Also, in general, Text-input controls will accept more data than can be simultaneously displayed within the control. The data you enter is still present even if you cannot see all of it at the same time.

Special Keys

— Scroll keys (LEFT, RIGHT, HOME, END) move the visible cursor. Note that the mouse (if enabled) may also be used to position the cursor. — ENTER(RET) key ends the edit and moves focus to next control. — TAB key ends the edit and moves to focus to next control. — SHIFT+TAB key ends the edit and moves to focus to previous control. — ESCAPE key aborts edit and restores the previous contents. — INSERT key toggles Insert/Overstrike input mode. — SHIFT+RIGHT_ARROW selects text toward the right — SHIFT+LEFT_ARROW selects text toward the left — CTRL+A selects all text in the control Note that the mouse (if enabled) may also be used to select text. — CTRL+C copies ‘selected’ text to the clipboard — CTRL+V pastes text from the clipboard at the cursor position

Note that cut-and-paste operations are currently limited to intra-application operations. Access to the X-server clipboard is currently disabled. The system clipboard is accessed through the ‘tbXClip’ library by the same author; however, this library is currently broken. Until this library is updated, to paste text from the system clipboard, you may use the special GNU/Linux SHIFT+CTRL+V key or paste using mouse button 2. See your system’s terminal documentation for details.

Please see Editing the Filename for an example of a Textbox control.




Pushbutton Controls

As the name implies, a Pushbutton control functions like any button in the physical world, such as the ’Balance Inquiry’ button on a bank machine or the ’Up’ button at an elevator. ’Pushing’ the button activates the functionality associated with that control.

Special Keys

— Enter(RET) or SPACE key activates the control. — TAB key (or ESC) moves focus to next control. — SHIFT+TAB key moves focus to previous control.

Please see Editing the Metadata for an example of Pushbutton controls.




Radiobutton Controls

Radio Button controls are so-named because of the array of channel-selection preset buttons often found on car radios. Selecting and de-selecting a Radio Button control is like turning a light switch on or off. For a Radio Button which has the input focus, toggle its on/off state by pressing the SPACE key. (The ’on’ state (but not the ’off’ state) may also be set via the ENTER(RET) key.)

There are two varieties of Radio Button, and each has its uses.

  1. Independent Radio Button
    An independent Radio Button is not associated with any other
    button, and is toggled on or off as described above.
  2. Radio Button Group
    A Radio Button group consists of two or more Radio Buttons logically linked together to form what programmers and math geeks call an ’exclusive-OR’ set.

    One, and only one of the buttons in a Radio Button group may be selected at any given time. If any button in the group is selected (set to the ’on’ state), then all other buttons in the group are reset (to the ’off’ state).

    To put it another way, exactly one group member must be in the ’on’ state at all times. This is similar to the channel-selection buttons on your car radio: you can listen to station A or to station B, but you cannot listen to two stations at once, AND you cannot listen to no station at all (unless you turn off the radio).

There are many visual ’styles’ for Radiobutton controls, but the functionality is the same for all. The ’standard styles’ are shown below.

┌────────────────────────────────────┐ │ │ Standard, 1 columns wide │ │ <> Standard, 3 columns wide │ │ [] Standard, 3 columns wide │ │ () Standard, 3 columns wide │ │ < > Standard, 5 columns wide │ │ [ ] Standard, 5 columns wide │ │ ( ) Standard, 5 columns wide │ │ │ └────────────────────────────────────┘

Please see Save Files Dialog for an example of Radiobutton controls.




Spinner Controls

A Spinner control provides for selecting a numeric value within a predetermined range. The UpArrow key and DownArrow key are used to cycle through the available values. Moving the input focus to another control sets the control’s value.

Special Keys

Because the range of values may be anywhere between a few integer values to thousands of decimal values, additional key combinations are defined to facilitate efficient selection of the desired value.

Please see Popularimeter dialog for an example of Spinner controls.



For Additional Information

Taggit’s dialog-based display and user interface are based on the NcDialog API library which was designed by the same author. For a more detailed description of the dialog window and its controls, please refer to the NcDialog API documentation.
See by the same author.




Next: , Previous: , Up: User Interface   [Contents][Index]

Menus





Next: , Up: Menus   [Contents][Index]

Menu Access

The Taggit application has a menu-driven user interface. The group of top-level menus is collectively known as the ‘Menu Bar’.

The menus are displayed in the language selected during application start up.

────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ File Edit View Help ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Archivo Corregir Examinar Asistencia ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ 文件 修正 查看 帮助 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

────┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├──── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Tập Tin Chỉnh Sửa Xem Xét Hỗ Trợ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀


A menu may be accessed either by using the mouse to click on the menu name, or by using the hotkey (shortcut key) assigned to the menu.

Because Taggit runs inside a terminal window, depending on your configuration, the terminal itself may capture some of these hotkeys for its own use, so two hotkeys are defined for each menu.

Standard Alternate Menu Hotkey Hotkey --------- -------- ----------- File Menu ALT+F ALT+SHIFT+F Edit Menu ALT+E ALT+SHIFT+E View Menu ALT+V ALT+SHIFT+V Help Menu ALT+H ALT+SHIFT+H

Of course these hotkeys are easiest to remember when the user interface is set to the English language because the hotkey is the first letter of the menu name. However, these hotkeys are valid regardless of which user-interface language is chosen.

Once a menu is open, the Right-Arrow and Left-Arrow keys will navigate to the next/previous menu.

──┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├─────────────────────────────── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navegación: ↑↓←→ o rueda de ratón Archivo Corregir Examinar Asistencia Corregir: Presione ESPACIO, o c ▀▀▀▀▀▀▀▀▀▀▀▀▀▀┌─────────────────────────────────┐▀▀▀▀ en el campo de object ═══╤═════════════│ Editar nombre de archivo A+N│══════▅▅▅▅═══════════════════════════ │ Editar Los Metadatos A+M│ │ Añadir Una imagen A+I│ Anular Ediciones C+Z │ Pista Relleno Automático C+T│ │ Duplicar un Campo C+D│ │ Ajustar el Título de la Canción │ │ Borrar los Metadatos del Archivo│ │ Borrar Todos los Metadatos │ │ Editar Preferencias │ └─────────────────────────────────┘

Scroll through the menu items using the Up-Arrow and Down-Arrow keys, OR by using the mouse scroll wheel.

To select a menu item:

a) click on the desired item, or b) scroll to the desired item and press the ENTER key

The menu will be closed when:

a) a selection is made b) by clicking anywhere outside the menu area c) by navigating past the right or left edge of the Menu Bar d) by pressing the ESCAPE key

The following chapters provide details about each menu item.

See File Menu.
See Edit Menu.
See View Menu.
See Help Menu.




Next: , Previous: , Up: Menus   [Contents][Index]

File Menu

──┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├─────────────────────────────── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigation: ↑↓←→ or mouse wheel File Edit View Help Edit: Press SPACE key or ┌───────────────────────────┐▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Click on target field ═══╤ Save ALL Files ═════════════════════════▅▅▅▅═══════════════════════════ │ Save File C+S│ │ Save File As AC+S│ │ Save Audio Data Only │ │ Save Tag Summary │ │ Play the Current File │ │ Refresh Displayed Data │ │ Command Shell │ │ Exit C+Q│ └───────────────────────────┘

Menu Items

╔═══════════╣ Save Tag Data Summary ╠════════════╗ ║ ║ ║ [ ◆ ] Summarize all source files ║ ║ ║ ║ [ ] Summarize only the highlighted file ║ ║ ║ ║ ║ ║ [ ◆ ] Write only fields which contain data ║ ║ ║ ║ [ ] Write all active fields, ║ ║ including blank fields ║ ║ ║ ║ ║ ║ ║ SAVE CANCEL ╚══════════════════════════════════════════════════╝

The features and controls of this dialog are:

The metadata are written in a simple list format.
Please see View Tag Summary in the ‘View Menu’ chapter for a sample of the formatted output.

See also the “Dump” command-line option: 'D' option.


┌─────────────┤ Refresh All Metadata ├─────────────┐ │ │ │ There are 4 files with edits pending. │ │ │ │ Do you want to discard these edits and re-read │ │ all the source files? │ │ │ │ │ YES NO └────────────────────────────────────────────────────┘

Note that the ‘edits-pending indicators’ will show which file(s) have edited, but unsaved tag data.
Please see change indicators for a discussion of these indicators.




Save Files Dialog

╔════════════════════╣ Save Metadata to Target File(s) ╠═════════════════════╗ ║ ║ Save changes for all 5 files. ╠══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ [ ◆ ] Save all fields which contain data. (default) ║ ║ (both active and inactive fields) ║ ║ ║ ║ [ ] Save active fields which contain data, ignoring empty fields. ║ ║ (all inactive fields ignored) ║ ║ ║ ║ [ ] Save all active fields, regardless of whether they contain data. ║ ║ (all inactive fields ignored) ║ ║ ║ ║ [ ] Write audio data only. ║ ║ (exclude all text and image metadata) ║ ║ ║ ║ [ ] Retain original source file. ║ ║ (original file renamed as a backup file) ║ ║ Example: 'Shout.mp3' becomes 'Shout.mp3~' ║ ║ ║ ║ ║ SAVE CANCEL ╚══════════════════════════════════════════════════════════════════════════════╝

The 'Save Files' dialog is invoked to save data for a single source file or to save data for all source files.

The dialog may be accessed either through one of the “save” options in the File Menu, or through the 'Save All' pushbutton. This dialog may also be invoked through the CTRL+S hotkey combination.

The 'Save Files' dialog contains five (5) options for setting the parameters of the save operation. Each option is controlled by a “Radio button” (yes/no button). These radio buttons are pre-conditioned to reflect the way in which the dialog was invoked. Each radio button may be set or reset manually before saving the data.

Note that the first four radio buttons are configured as an exclusive-OR (XOR) group, meaning that exactly one button of the group is set at any given time. The fifth radio button may be toggled independently.


Technical Notes

┌────────────────┤ Warning! Warning! ├────────────────┐ │ │ │ One or more source files in the list have been moved, │ │ renamed, deleted or are no longer read/write accessible. │ │ This may cause processing errors. │ │ │ │ Do you want to proceed? │ │ │ │ │ PROCEED ABORT └──────────────────────────────────────────────────────────┘



Next: , Previous: , Up: Menus   [Contents][Index]

Edit Menu

──┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├─────────────────────────────── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigation: ↑↓←→ or mouse wheel File Edit View Help Edit: Press SPACE key or ▀▀▀▀▀▀▀▀▀▀▀▀▀▀┌─────────────────────────────────┐▀▀▀▀ Click on target field ═══╤═════════════│ Edit Filename A+N│══════▅▅▅▅═══════════════════════════ Edit Metadata A+M │ Add Image File AC+I│ │ Edit Image Stats AC+E│ │ Undo Tag Edits C+Z│ │ Autofill Track Data C+T│ │ Duplicate Field C+D│ │ Set Song Title │ │ Popularity and Play Counter │ │ Clear File Metadata │ │ Clear All Metadata │ Edit Preferences └─────────────────────────────────┘

Menu Items


╔══════════════════════╣ Insert Image ╠══════════════════════╗ ║ Image Filename ║ /home/sam/SoftwareDesign/1_TestData/Foghat_Live.jpg ║ MIME Type: "image/jpeg" ║ ║ Image Size: 10,492 bytes ║ ║ ║ ║ Picture ┌───────────────────────────────────┐ ║ Category Cover (front) └───────────────────────────────────┘ ║ ║ ║ Image Description (64 chars max) ║ Foghat-Live 1977 Vinyl album, front. ║ ║ ║ ║ SAVE SAVE TO TO CANCEL CURRENT FILE ALL FILES ╚══════════════════════════════════════════════════════════════════╝

The features and controls of this dialog are as follows.

To view a list of images which are to be embedded into the target audio file, please see View Tag Summary item in the View Menu. Please see Edit Image Stats command described below to edit the setup data for embedded images.

Special Note for RTL Languages: Textbox controls can be used to edit either LTR (left-to-right) or RTL (right-to-left) language data. For RTL (right-to-left) user-interface languages, an additional pushbutton will appear at the lower left corner of this dialog, labelled as "RTL" which allows the contents of the field to be displayed in reverse order.
Please see RTL language support for additional information on RTL user-interface languages.



╔═════════════════════╣ Edit Image Setup ╠═════════════════════╗ ║ Image Filename ║ /tmp/TG_dOaQ2h/TG_Eue3VV.jpg ║ MIME Type:"image/jpeg" ║ ║ Image Size: 11,020 bytes ║ ║ ║ ║ Picture ┌───────────────────────────────────┐ ║ Category Lead artist/lead performer/soloist └───────────────────────────────────┘ ║ ║ ║ Image Description (64 chars max) ║ 2012 re-release CD insert ║ ║ NEXT DELETE SAVE THIS CANCEL IMAGE IMAGE ╚══════════════════════════════════════════════════════════════════╝

The features and controls of this dialog are as follows.

Special Note for RTL Languages: Textbox controls can be used to edit either LTR (left-to-right) or RTL (right-to-left) language data. For RTL (right-to-left) user-interface languages, an additional pushbutton will appear at the lower left corner of this dialog, labelled as "RTL" which allows the contents of the field to be displayed in reverse order.
Please see RTL language support for additional information on RTL user-interface languages.


╔═══════════════════════════════╣ Duplicate Field Data ╠═══════════════════════════════╗ ┌────────┤ FIELD NAME ├────────┐ Source Text ║ Title Dazed and Confused Artist Album Track Year Genre Guest Artist or Group Record Label, Publisher Composer(s) Lyricist Remixed by DUPLICATE CANCEL Copyright Message Content owner/licensee Select the field to be duplicated. ║ Comment The contents of the corresponding field in the ║ Record Date highlighted file will be displayed in the textbox.║ Record Time The displayed data may be edited. ║ Record Date Supplement Press the "Duplicate" button to write the text ║ Playback Time (mSec) into the target field of all source files. ║ Audio Data Size Beats Per Minute (Note: Inactive fields may not be duplicated.) └────────────────────────────────┘ ╚════════════════════════════════════════════════════════════════════════════════════════╝

┌─────────────────┤ Set Song Title ├──────────────────┐ │ │ │ Do you want to set the "Title" field for all files │ │ based on the name of the file? │ │ │ │ Example Filename: My Heart Will Go On.mp3 │ │ Title becomes: My Heart Will Go On │ │ │ │ │ YES NO └───────────────────────────────────────────────────────┘

╔══════════════════╣ Adjust Popularity Meter ╠══════════════════╗ ☻☻☻½ 175± Set Popularity Meter ║ The Popularity Meter is implemented as a numeric value ║ ║ between 0 and 255. Media players generally represent this ║ ║ as a number of "stars" (between 0 and 5 stars). ║ ║ Note: mapping of this value to the number of "stars" varies ║ ║ among media players. Please see documentation for details. ║ ║ ║ ║ ║ Taggit 0.0.02 Software Samurai Popularity Message ║ Use this field to enter an email address or other message ║ ║ related to the Popularity Meter. ║ ║ ║ ║ ║ 0± Set Play Counter ║ The Play Counter is an integer value representing the number ║ ║ of times the song has been played by the media player. ║ ║ Many media players have a configuration option to enable ║ ║ or disable this feature. ║ ║ ║ SAVE CANCEL ╚═════════════════════════════════════════════════════════════════╝

The features and controls of this dialog are:

Special Note for RTL Languages: For RTL (right-to-left) user-interface languages, an additional pushbutton will appear at the lower left corner of this dialog, labelled as "RTL" which allows the popularity message field to be displayed and in reverse order.
Please see RTL language support for additional information on RTL user-interface languages.





Next: , Previous: , Up: Menus   [Contents][Index]

View Menu

──┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├─────────────────────────────── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigation: ↑↓←→ or mouse wheel File Edit View Help Edit: Press SPACE key or ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀┌────────────────────────┐ Click on target field ═══╤══════════════════════════ Set All Fields Active ══▅▅▅▅═══════════════════════════ │ View Tag Data Summary │ │ Sort File List >│ │ Shift File Down A+DN│ │ Shift File Up A+UP│ │ Target Free Space │ │ View Image Data A+I│ │ RTL InvertFieldData C+R│ │ Set Color Scheme │ └────────────────────────┘

Menu Items


┌─────────────┤ File System Information ├─────────────┐ │ Target filesystem information: │ │ │ │ File System Type: EF53 - ext2/ext3 │ │ File System ID: 62399710D41085CF │ │ │ │ Total Blocks: 70,522,296 │ │ Free Blocks: 56,868,259 │ │ Avail Blocks: 53,280,163 │ │ Used Bytes: 55.9269G │ │ Free Bytes: 218.236G │ │ │ │ │ │ │ OK └───────────────────────────────────────────────────────┘

╔══════════════════╣ View Image Data ╠═══════════════════╗ ║ Low Rider - War.mp3 ║ Picture type : 03h - Cover (front) MIME type : image/jpeg Image size : 9,755 bytes Image file : /tmp/TG_CW2VrA/TG_1c2Zny.jpg Description : Front cover art, Dazed and Confused Soundtrack. The Medicine Label, 1993. ║ ║ View Image ║ ║ NEXT DONE ╚══════════════════════════════════════════════════════════╝

Special Note for RTL Languages: For RTL (right-to-left) user-interface languages, an additional pushbutton will appear at the lower left corner of this dialog, labelled as "RTL" which allows the image description field to be displayed in reverse order.
Please see RTL language support for additional information on RTL user-interface languages.


Technical Notes:
If an external image-viewer application is invoked, Taggit will open the file using the default image viewer specified by your desktop environment. This is done by calling the 'xdg-open' system utility with the name of the image file.

For most installations, the default viewer is set to “Shotwell.” However, Shotwell is overkill for simply viewing images. We recommend setting “Image Viewer” aka Eye-of-Gnome (eog) as the default image viewer because it is lightweight and because cycling through the images in the capture directory is a simple operation.

An alternative image viewer which is not generally installed by default is the Free Software Foundation’s “gThumb” which provides not only the ability to view image thumbnails, but also provides basic image editing.
See <https://apps.fedoraproject.org/packages/gthumb>
or <https://apps.ubuntu.com/cat/applications/precise/gthumb/>
or <https://directory.fsf.org/wiki/Gthumb>

To set the default image viewer:

  1. open Nautilus (or other file manager)
  2. find a file with an extension of ’jpg’
  3. right-click the file and select "properties"
  4. click the "open-with" tab
  5. select the desired application
  6. click the "set-as-default" button
  7. repeat steps b through f for a file with an extension of ’png’

The image files extracted by Taggit while scanning the source files are written to a temporary directory, and will be deleted when Taggit closes. To save an image as a separate file, invoke the external viewer and then chose 'Save-as' from the viewer’s menu.

Please see MP3 Embedded Image for more information on encoding of image data.


╔══════════════════════╣ Set Application Color Scheme ╠══════════════════════╗ ║ ║ ║ Select Color ║ ┌─────────────────┐ ╔═══════════════╣ Taggit - v:0.1.00 ╠═══════════════╗ Black ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Red File Edit View ║ Green Save All ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Brown ╠════════════════════════╦════════════════════════════╣ Blue ║ F M File Name ▼ ║ Artist Track ║ Magenta School's Out Alice Cooper 1 / 14 Cyan ║ ║ ║ Gray Slow Ride Foghat 2 / 14 Default ║ ║ ║ └─────────────────┘ Rock and Roll Hoo Rick Derringer 3 / 14 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀ Love Hurts Nazareth 4 / 14 ╚════════════════════════╩════════════════════════════╝ ║ ║ ║ ║ SAVE CANCEL ╚══════════════════════════════════════════════════════════════════════════════╝

The Color Scheme may also be specified in the configuration file.
See Configuration, for details.

The Color Scheme may also be specified as a command-line argument.
Please see 'c' option in the chapter on invoking the application.




Next: , Previous: , Up: Menus   [Contents][Index]

Help Menu


──┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├─────────────────────────────── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigation: ↑↓←→ or mouse wheel File Edit View Help Edit: Press SPACE key or ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀┌────────────────────┐ Click on target field ═══╤═══════════════════════════════════════│ Taggit Help │═════════════════════════ │ Help (HTML) │ │ Quick Help │ About Taggit └────────────────────┘

Menu Items

╔═══════════════════════╣ About Taggit ╠═══════════════════════╗ ║ Taggit : Audio file metadata (tag) editor and demo program for ║ ║ development of a multilingual user interface. ║ ║ Version: 0.0.01 ║Copyright: (c) 2016-2017 Mahlon R. Smith, The Software Samurai ║ ║ Beijing University of Technology - Beijing, PRC ║ 马伦教授 北京工业大学 - 北京,中华人民共和国            ║ ║ ║Developed under Fedora Linux 20, using GNU G++ (Gcc v: 4.8.3) ║ ║Software released under GNU General Public License, version 3, ║ ║and documentation under GNU Free Documentation License, version 1.3 ║ ║ Bugs, suggestions, or possible praise? ║ ║ Please contact the author at: http://www.SoftwareSam.us/ ║ ║ ║ CLOSE SUPPORT INFORMATION ╚════════════════════════════════════════════════════════════════════╝

Tech Support Request

When submitting a request for technical support, it is helpful for that request to include certain information about the application and the system on which it is running.

This information is collected in a sub-dialog which is invoked by pressing the 'SUPPORT INFORMATION' pushbutton.

╔═══════════════╣ Technical Support Information ╠════════════════╗ Please include this information Dynamic (shared) Libs with all tech support requests. libncursesw.so.5 ║ ║ NcDialog API library : 0.0.29 libtinfo.so.5 ║ ║ libstdc++.so.6 ║ ║ ncursesw library : 5.9.20130511 libm.so.6 ║ ║ libgcc_s.so.1 ║ ║ Locale setting : en_US.utf8 libc.so.6 ║ ║ (English) libdl.so.2 ║ ║ ║ SAVE TO FILE CLOSE ╚══════════════════════════════════════════════════════════════════╝

Pressing the 'SAVE TO FILE' pushbutton will save this information to a plain-text file which can be edited to add specific information related to the technical support request.
Also, see Technical Support for more information.




Previous: , Up: Menus   [Contents][Index]

Sort-by Submenu

──┤ Taggit - v:0.0.01 (c)2016-2017 The Software Samurai ├─────────────────────────────── ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ Navigation: ↑↓←→ or mouse wheel File Edit View Help Edit: Press SPACE key or ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀┌────────────────────────┐ Click on target field ═══╤══════════════════════════│ Specify Active Fields │══▅▅▅▅═══════════════════════════ │ View Tag Data Summary ┌────────────────┐ │ Sort File List > Filename │ Shift File Down A+DN Title │ Shift File Up A+UP Album │ Target Space Available Track │ View Image Data A+I Artist │ Set Color Scheme └────────────────┘ └────────────────────────┘


A “submenu” is a menu attached to an item in the higher-level menu.

In this case, the 'Sort-by' submenu is attached to the 'Sort File List' item in the 'View' menu. To access this menu:

1) Open the 'View' menu 2) Highlight the 'Sort File List' item 3) Press either the ENTER key or the Right-Arrow key.

Menu Items

This menu displays the list of fields on which the display data may be sorted.
All options sort in ascending order (low-to-high).


The default field on which to sort may be specified in the configuration file.
Please see Configuration for details.

The initial sort field may also be specified as a command-line option.
Please see 's' option for more information.






Next: , Previous: , Up: User Interface   [Contents][Index]

Editing the Filename

Modify the name of the target file.

By default, the target (output) file to which the edited tag data are written will be the same as the source file unless the save option used writes to a copy of the source file while leaving the source file unchanged.

To explicitly change the name of the target file, invoke the 'Edit Filename' option from the Edit, menu which opens the dialog shown below so that a new filename may be specified.

This dialog may also be invoked by clicking on the filename field to be edited or by pressing the ALT+N hotkey.
See Navigation, chapter for details.


╔═════════════╣ Edit File Name ╠═════════════╗ Current File Name: Low Rider.mp3 ║ New File Name: 10 Low Rider - Dazed & Confused Soundtrack.mp3 Ctrl+C = Copy, Ctrl+X = Cut, Ctrl+V = Paste INSERT key toggles insert/overstrike. ║ ║ ║ ║ ║ ║ DONE CANCEL ║ ║ Clear Edits ║ ║ ║ [ ] Copy from Title field ║ Example: Let It Be.mp3 ║ ║ [ ◆ ] Combine Title + Artist ║ Example: Let It Be - Beatles.mp3 ║ ║ [ ] Combine Artist + Title ║ Example: Beatles - Let It Be.mp3 ║ ║ [ ◆ ] Insert track number ║ Example: 12 Get Back - Beatles.mp3 ║ ║ ║ ║ [ ◆ ] Duplicate pattern to all file names. ║ ╚══════════════════════════════════════════════════╝

The features and controls of this dialog are:


Several options are available to modify the name of the target file. The simplest is to type a new filename into the Textbox control at the top of the ‘Edit Filename’ dialog.

In addition to this straightforward filename modification, the Edit Filename dialog offers the following options to programatically modify the name of the file under edit using data from the 'Title', 'Artist' and 'Track' tag fields; and optionally apply that modification pattern to the names of all listed files. Of course the data in these source fields should be initialized before using them to construct the filename(s).

Renaming the target file is often useful because when a group of audio files are ripped from a CD, they are often titled in unhelpful ways such as ‘track01.oga’, ‘track02.oga’ and so on. It is tedious to rename each of these files individually, so the following programatic naming options are provided.

Using Greenday’s “American Idiot” album as an example, we will demonstrate these options.

For all files modified by the operation, the edits-pending indicator will be set to show that the files’ data have changed, but that the changes have not yet been written to the target file.
Please see change indicators for additional information.

Special Note for RTL Languages: Textbox controls can be used to edit text for either LTR (left-to-right) or RTL (right-to-left) languages. For RTL (right-to-left) user-interface languages, an additional pushbutton will appear at the left edge of this dialog, labelled as "RTL" which allows the contents of the field to be displayed in reverse order.
Please see RTL language support for additional information on RTL user-interface languages.




Next: , Previous: , Up: User Interface   [Contents][Index]

Editing the Metadata

Each metadata field may be edited by opening the “Edit Metadata Fields” dialog.

The “Edit Metadata Fields” dialog may be opened in several different ways.
The easiest and most efficient way is to click on the field to be edited.
Place the mouse pointer on the desired field and press the left mouse button.

For the highlighted file, the ‘Edit Metadata Fields’ dialog may be accessed by selecting the ‘Edit Metadata’ item from the Edit menu. The hotkey for the ‘Edit Metadata’ menu item is 'ALT+M', or alternatively, just press the 'ENTER' key.

Text entry is free-form for all fields; however, the tag specification limits the contents of certain fields for compatibility with media players. These limitations or special formatting rules are briefly explained in the description for the field.


╔═════════════════════════════╣ Edit Metadata Fields ╠═════════════════════════════╗ File Name: Bad Romance - Lady Gaga.mp3 ║ Internet Radio Station Owner ◀━╸ prev Sirius XM Satellite Radio, Sirius XM Radio Inc. next ╺━▶ up ∆ (modified) ║ down ∇ ║ Name of the owner of the internet radio station from which ║ ║ the audio is streamed. ║ ║ ║ DONE CANCEL ║ ║ Undo Changes ╚════════════════════════════════════════════════════════════════════════════════════════╝

The features and controls of this dialog are:





Special Fields

The following fields have an additional Pushbutton control for selecting values from a list or for other special processing.

  CODE    DESCRIPTION    CODE    DESCRIPTION
  ( 0) Blues (63)    Jungle
  ( 1) Classic Rock (64)    Native American
  ( 2) Country (65)    Cabaret
  ( 3) Dance (66)    New Wave
  ( 4) Disco (67)    Psychadelic
  ( 5) Funk (68)    Rave
  ( 6) Grunge (69)    Showtunes
  ( 7) Hip-Hop (70)    Trailer
  ( 8) Jazz (71)    Lo-Fi
  ( 9) Metal (72)    Tribal
  (10) New Age (73)    Acid Punk
  (11) Oldies (74)    Acid Jazz
  (12) Other (75)    Polka
  (13) Pop (76)    Retro
  (14) R&B (77)    Musical
  (15) Rap (78)    Rock & Roll
  (16) Reggae (79)    Hard Rock
  (17) Rock (80)    Folk
  (18) Techno (81)    Folk-Rock
  (19) Industrial (82)    National Folk
  (20) Alternative (83)    Swing
  (21) Ska (84)    Fast Fusion
  (22) Death Metal (85)    Bebob
  (23) Pranks (86)    Latin
  (24) Soundtrack (87)    Revival
  (25) Euro-Techno (88)    Celtic
  (26) Ambient (89)    Bluegrass
  (27) Trip-Hop (90)    Avantgarde
  (28) Vocal (91)    Gothic Rock
  (29) Jazz+Funk (92)    Progressive Rock     
  (30) Fusion (93)    Psychedelic Rock
  (31) Trance (94)    Symphonic Rock
  (32) Classical (95)    Slow Rock
  (33) Instrumental (96)    Big Band
  (34) Acid (97)    Chorus
  (35) House (98)    Easy Listening
  (36) Game (99)    Acoustic
  (37) Sound Clip (100)   Humour
  (38) Gospel (101)   Speech
  (39) Noise (102)   Chanson
  (40) AlternRock (103)   Opera
  (41) Bass (104)   Chamber Music
  (42) Soul (105)   Sonata
  (43) Punk (106)   Symphony
  (44) Space (107)   Booty Bass
  (45) Meditative (108)   Primus
  (46) Instrumental Pop (109)   Porn Groove
  (47) Instrumental Rock (110)   Satire
  (48) Ethnic (111)   Slow Jam
  (49) Gothic (112)   Club
  (50) Darkwave (113)   Tango
  (51) Techno-Industrial (114)   Samba
  (52) Electronic (115)   Folklore
  (53) Pop-Folk (116)   Ballad
  (54) Eurodance (117)   Power Ballad
  (55) Dream (118)   Rhythmic Soul
  (56) Southern Rock (119)   Freestyle
  (57) Comedy (120)   Duet
  (58) Cult (121)   Punk Rock
  (59) Gangsta (122)   Drum Solo
  (60) Top 40 (123)   A capella
  (61) Christian Rap (124)   Euro-House
  (62) Pop/Funk (125)   Dance Hall

While it is certainly possible to create your own genre such as “Billy Idol’s Drug-induced-fog Rock, the Cyberpunk Years”, for compatibility with streaming software, an entry from the published list is recommended.

Technical Note: While every effort has been made to translate the Taggit user interface for the supported languages, we were not able to adequately translate the above list. The reason for this is that many of the categories are slang or made-up words which do not translate well across cultures and languages. Sorry about that.


  CODE    LANGUAGE    CODE    LANGUAGE
  zho Mandarin group (官話) pus    Pashto
  spa Spanish kan    Kannada
  eng English hsn    Xiang
  hin Hindi mal    Malayalam
  ara Arabic sun    Sudanese
  por Portuguese hau    Hausa
  ben Bengali ori    Odiya
  rus Russian bur    Burmese
  jpn Japanese hak    Hakka
  pan Punjabi ukr    Ukrainian
  deu German bho    Bhojpuri
  jav Javanese tgl    Tagalog
  wuu Wu (incl Hu dialect) yor    Yoruba
  msa Malay mai    Maithili
  tel Telugu uzb    Uzbek
  vie Vietnamese snd    Sindhi
  kor Korean amh    Amharic
  fra French ful    Fula
  mar Marathi ron    Romanian
  tam Tamil orm    Oromo
  urd Urdu ibo    Igbo
  tur Turkish aze    Azerbaijani
  ita Italian awa    Awadhi
  yue Yue zhx    Gan (and misc.  Chinese dialects)
  tha Thai ceb    Cebuano
  guj Gujarati nld    Dutch
  cjy Jin kur    Kurdish
  nan Southern Min  (Hokkien, Teochew) srp    Serbian
  fas Persian hrv    Croatian
  pol Polish     



Previous: , Up: User Interface   [Contents][Index]

UI Languages

Taggit can support any reasonable number of user-interface languages.

The application is designed specifically to support multiple languages, and adding a new UI language requires only translation of the text and verification that the text will be displayed aesthetically within the dialog windows.

So long as the estabilshed pattern is followed, there is little chance that adding a UI language will break the code.
The basic steps are to append a new element to the AppLang enumerated type, and then search for all the references to the Taggit data member 'cfgOpt.appLanguage' and then add the translated text to the associated array.

The author is happy to work with native speakers of other languages to translate the user interface titles, labels, descriptions and instructions into additional languages.


Adding A New User Interface Language

Taggit is designed specifically to enable easy integration of new user interface languages. Some programming experience is certainly necessary, specifically experience with C++. Additionally, a general understanding of the author’s NcDialog API interface for console-based applications is helpful but not necessary.

The overarching consideration is to add the new UI language without breaking the existing code and without compromising display of the current interface languages. It should be unnecessary to change the actual code in any way. Simply add your translation to the data array.

Example text array

Example taken from Cmd_SetColorScheme() method: //* Control labels * const char* Labels[][scsCTRLS + 1] = { { // English " SAVE ", // 'save' pushbutton " CANCEL ", // 'cancel' pushbutton "Select Color", // 'select' scrollbox " Set Application Color Scheme ", // Dialog title }, { // Espanol " GUARDAR ", // 'save' pushbutton " CANCELAR ", // 'cancel' pushbutton "Selecciona el Color", // 'select' scrollbox " Establecer el Esquema de Color de la Aplicación ", // Dialog title }, { // Zhongwen " 保存 ", // 'save' pushbutton " 取消 ", // 'cancel' pushbutton "选择颜色", // 'select' scrollbox " 设置应用颜色方案 ", // Dialog title }, { // TiengViet " Để Dành ", // 'save' pushbutton " Hủy Bỏ ", // 'cancel' pushbutton " Chọn Màu", // 'select' scrollbox " Đặt Bảng màu ứng Dụng ", // Dialog title }, { // YOUR NEW UI LANGUAGE HERE " xxxx ", // ’save’ pushbutton " xxxxxx ", // ’cancel’ pushbutton "xxxxxxxxxxxx", // ’select’ scrollbox " xxxxxxxxxxxxxxxxxxxxxxxxxxxx ", // Dialog title }, } ;
  1. Add a member to the ‘AppLang’ enumerated type. This value functions as an index into the first level of the two-level array of text data as shown above.
    enum AppLang : short { enLang = ZERO, // English esLang, // Español (Spanish) zhLang, // Zhōngwén (中文) (Chinese, simplified) viLang, // Tiếng Việt (Vietnamese) xxLang, // YOUR NEW UI LANGUAGE HERE locLang // language taken from locale if supported, // else default language } ;

    The following would reference the text for the “Save” pushbutton control:
    Labels[language][saveButton]

  2. Add a corresponding element to the ‘AppDirection’ array indicating whether the new language is written LTR (left-to-right) or RTL (right-to-left).
    const bool AppDirection[] = { false, // English, LTR false, // Espanol, LTR false, // Zhongwen, LTR false, // TiengViet, LTR xxxxx, // YOUR NEW UI LANGUAGE HERE } ;

    On startup, the value from this array corresponding to the selection of user interface language will be used to initialize the application’s configuration flag, Taggit::cfgOpt.rtl.

  3. Add an entry to the “alStrings” and “okText” arrays.
    const wchar_t* const alStrings[] = { L"English", L"Español", L"Zhōngwén", L"TiếngViệt", L"xxxxxxx", // YOUR NEW UI LANGUAGE HERE L"(from locale)", } ; const char* const okText[4] = { " ^OK ", // English " BUEN^O ", // Espanol " 好 ", // Zhongwen " Được ", // TiengViet " xxxxx ", // YOUR NEW UI LANGUAGE HERE } ;
  4. For each of the following methods, add translated text to the arrays of user interface text. For most methods, the text data array will be very similar to the Labels[][] example shown above. A few methods, the Cmd_InsertImage() method for example, require somewhat more complex text definitions due to the complexity of the code itself.

    • InitAppControls (menus)
    • InitStaticDisplay
    • Warning (various informational messages)
    • UpdateFilenameWindow
    • UpdateMetadataWindow (column headings)
    • uiEditFilename
    • uiEditMetadata
    • uiemLoadField (tag field descriptions)
    • uiemFxSelect (data for pre-defined fields)
    • uiEditsPending
    • Cmd_ReportTargetStats
    • Cmd_SetColorScheme
    • Cmd_WriteTargetFile
    • wtfReverifySource
    • Cmd_InfoHelp (call to the info reader)
    • Cmd_QuickHelp (help for hotkeys)
    • Cmd_HelpAbout
    • haSupportInfo (tech support request form)
    • ctsPrompt (tag summary setup)
    • ctsSummarize (tag summary report)
    • ctsVerifySave
    • Cmd_RefreshMetadata
    • ccmClearMetadata
    • Cmd_DuplicateField
    • Cmd_SetSongTitle
    • Cmd_Popularimeter
    • Cmd_ReportImage
    • Cmd_InsertImage
    • mptDecodeImageFrame (pType[][PIC_TYPES] array)

    The above list was definitive as of version 0.0.02; however, as the application develops, additional points of update may arise. In general, any method that references the Taggit::cfgOpt.appLanguage data member will need to be updated when a new UI language is added.

    It is not necessary to translate text that is used strictly for diagnostic and debugging messages. These messages are displayed only in English because they are used only during development.

  5. Test each entry to be sure it is properly (and pleasingly) displayed within the available space.

If you are having trouble with some aspect of integrating your language into the application, please see Technical Support, and the author will be glad to assist in getting the new language fully integrated.


RTL User Interface Languages

While Taggit initially supports four (4) languages, these are all LTR (Left-To-Right) languages. The application has been extensively tested using simulated RTL data, so it is hoped that adding an RTL user-interface language will be straightforward.

Textbox controls can be used to edit both LTR (left-to-right) and RTL (right-to-left) language data. However, Taggit and the underlying NcDialog API do not automatically determine the language being displayed, so it is left to the user to specify how the text will be displayed and edited.

For RTL user-interface languages, an additional pushbutton will appear at the lower left corner of most dialogs so that data may be viewed and/or edited in the language it was originally written. This additional Pushbutton, labelled as "RTL" allows the contents of the field to be displayed in reverse order. The ‘hotkey’ for this Pushbutton is the ‘CTRL+R’ key combination.

Numeric fields, including date fields will be represented in Hindu-Arabic (Western Arabic) glyphs (0 through 9) which are inherently LTR text. Non-numeric text is displayed, and may be edited in either LTR or RTL format. If the text sequence is displayed in reverse, then press the "RTL" Pushbutton (hotkey: CTRL+R) to display and edit the text in the opposite direction. For entry of mixed RTL/LTR text, choose the most convenient display format. Please refer to the example dialog below which is the Save Tag Summary dialog as it would appear with the user-interface language set to Arabic.

If you are entering tag-data text in Hebrew, Arabic, Persian, Pashto or other Right-to-Left languages, first be sure that your favorite media player can correctly display the data, (many cannot).


╔═══════════╣ ةمالعلا تانايب صخلم ظفح ╠═══════════╗ ║ ║ .ردصملا تافلم عيمج صيخلت [ ◆ ] ║ ║ ║ .طقف يلاحلا فلملا صيخلت [ ] ║ ║ ║ ║ ║ .طقف تانايب ىلع يوتحت يتلا لوقحلا بتكا [ ◆ ] ║ ║ ║ ،ةطشنلا لوقحلا عيمج بتكا [ ] ║ .ةغرافلا لوقحلا كلذ يف امب ║ ║ ║ ║ ⇦⇦⇦ RTL ظفح ءاغلإ ╚══════════════════════════════════════════════════╝

Programmer’s Note: During development of support for RTL user interface languages, we defined the “FAKE_RTL” debugging switch which is used to fool the interface code into thinking that whatever the current interface language may be, it should be rendered as if it were RTL data. This has allowed us to exercise the internal direction flags and conditional expressions, position messages and to test RTL editing of data fields without having to translate the entire interface into Hebrew. (That will be a much bigger challenge. !אנו נחודש )

╔══════════════════════════════════════════════════════════════╗ ║ ║ This sentence is in Hebrew: .הגיע הזמן לסגור את משחק הווידאו ולעשות את שיעורי הבית שלך      ║ ║ :drawkcab deyalpsid si ecnetnes sihT       ךלש תיבה ירועיש תא תושעלו ואדיווה קחשמ תא רוגסל ןמזה עיגה. ║ ║ ╚══════════════════════════════════════════════════════════════╝

Please refer to the NcDialog API documentation for a thorough discussion of the features and challenges of designing a user interface which supports both LTR and RTL languages.




Next: , Previous: , Up: Top   [Contents][Index]

Configuration

The configuration file provides default values for all operational parameters, and may be customized using any plain-text editor to provide the desired default values to be loaded on application startup.

The configuration file is fully self-documenting, so it is hoped that selection of parameters will be straightforward.

The available options are:

  1. Language
    Select the language for the user interface.

    By default, the language for the user interface is automatically determined based on the locale specified by the terminal environment.

    The language specified must be supported by the terminal environment’s locale. If not, then some characters may be rendered incorrectly. Any UTF-8 compliant locale will render most text correctly for any language, but see the ’Locale’ option below.

    The following parameters are available for this option:

    • locale (default)
      Take the language from the terminal’s locale setting.
    • Espanol
      Spanish
    • Zhongwen
      Chinese, simplified (简体中文)
    • TiengViet
      Vietnamese
    • English
      English, U.S. (default if selection by locale fails)

    Please see 'l' option invocation option for more information.


  2. Locale
    Specify an alternate locale for text rendering.
    By default, the application uses the locale specified in the terminal’s environment. While this is generally correct, if the language specified in the above option does not match the locale, this option may be used to specify a matching locale.

    The following parameters are available for this option:

    • locale (default)
      Use the locale specified in terminal’s environent.
    • Any locale that specifically supports UTF-8 encoding.
      Examples:
         es_MX.utf8 (Espanol   - Mexico)
         zh_CN.utf8 (Zhongwen  - mainland China)
         vi_VN.utf8 (TiengViet - Vietnam)
         en_US.utf8 (English   - United States)
      

    Please see 'L' option invocation option for more information.


  3. ColorScheme

    The Color Scheme is the combination of text and background colors used to draw the application’s dialog windows.

    The following parameters are available for this option:

    • Default (default)
      Cyan borders and background; blue dialog windows and menus; The default color scheme is optimized for contrast and readability.
    • Black
      bright white foreground, black background
    • Red
      white foreground, red background
    • Green
      white foreground, green background
    • Brown
      white foreground, brown background
    • Blue
      white foreground, blue background
    • Magenta
      white foreground, magenta background
    • Cyan
      white foreground, cyan background
    • Gray
      white foreground, gray background

    Please see Set Color Scheme, item of the ‘View Menu’ for more information on setting the application’s colors.
    Also, please see 'c' option invocation option.


  4. EnableMouse
    Enable/disable mouse input to supplement the keyboard user interface.

    Note that while full application functionality is available through the keyboard interface alone, it is generally faster and more intuitive to use the mouse interface.

    To activate the mouse interface, the mouse must have at least one button and a ScrollWheel.

    A Left Button click is generally interpreted as selecting the item under the mouse pointer i.e. the field to be edited or one of the user-interface controls (menus, pushbuttons, etc.) Clicking the dialog borders will vertically/horizontally scroll the filename and/or the tag-field data. While hovering over the filename list or field list, ScrollWheel mouse events will scroll the data. (equivalent to the ’UpArrow’ or ’DownArrow’ keys).

    The ’Ctrl’, ’Shift’ or ’Alt’ modifier keys when pressed in combination with a mouse click or ScrollWheel event will modify the interpretation of the action. All other mouse events will be ignored.

    The following parameters are available for this option:

    • enable (default)
      Enable mouse support.
    • disable
      Disable mouse support.

    Please see Navigation for more information on application mouse support.
    Also, please see 'm' option invocation option.


  5. SortOrder
    Specify the order in which the source files are displayed. Files are sorted alphabetically, low-to-high, according to the data in the specified field. Sorting is case sensitive.

    Sorting on a particular field is not foolproof. Metadata (tag) fields may, or may not contain non-whitespace data, so sorting by these fields may be ineffective. If a metadata field contains no data, or if multiple source files contain the same data for the specified field, then a secondary sort will be done by filename. Because the filename field is always populated, it is the default field on which the files are sorted.

    The following parameters are available for this option:

    • Filename (default)
      Sort alphabetically on ‘Filename’ field.
    • Title
      Sort alphabetically on ‘Title’ metadata field.
    • Track
      Sort numerically on ‘Track’ metadata field
    • Album
      Sort alphabetically on ‘Album’ metadata field
    • Artist
      Sort alphabetically on ‘Artist’ metadata field
    • None
      No Sort: Display source files in the order in which they are specified on the command line OR in the order they are stored in the directory file.

    Please see 's' option invocation option for more information.


  6. PreserveSource
    Protect the original source file. Instead of directly modifying the source file, write all modifications to a copy of the original file, leaving the original file unmodified.

    This option may be used to create a test file or a file with different tag data without risk to the original file.

    The following parameters are available for this option:

    • Preserve
      Write all modifications to a COPY of the sourcefile. The original source file will not be modified.
    • Overwrite (default)
      Write all modifications to the original sourcefile. The edited metadata will replace any existing metadata in the target file.

    Please see 'P' option invocation option for more information.


  7. StripMetadata
    Discard all pre-existing metadata, leaving only the audio data. New metadata may be added during the editing process.

    Many tag editors, including media players insert incorrect, invalid, poorly-formatted or meaningless metadata by default. They may also insert huge, empty records for no particular reason. Also, when files are downloaded from questionable music sites, these sites will often insert their own advertising messages. This option allows all these data to be automatically removed from the source file.

    The following parameters are available for this option:

    • Strip
      Discard any existing metadata from the sourcefile.
    • Retain (default)
      Retain and display all existing metadata (default).

    Please see 'i' option invocation option for more information


  8. TextEncoding
    This option sets the preferred text encoding for text tag fields.

    For MP3 media files, text frames may be encoded in one of several formats. The reasons for these formats are historical. ASCII is the ancient and venerable encoding in the computer world; however it supports only the basic 96 characters. Its successor, ISO 8859-1 added support for European characters but ISO 8859-1 encoding is not used in modern systems.
    UTF-16 (big-endian and little-endian) is a crippled and inefficient encoding which is unfortunately the standard embraced by Windows(tm). This should come as no surprise since the Windows folks seem to do everything in the most inconvenient and illogical way possible.

    Versions id3v2.2 and id3v2.3 of the MPEG standard support two encodings:
    ASCII (American Standard Code for Information Interchange)
    (see note below)
    UTF-16, big-endian with BOM (Byte-Order-Mark)
    Version id3v2.4 of the standard supports two additional encodings:
    UTF-16BE, big-endian without BOM
    UTF-8 encoding

    The following parameters are available for this option:

    • ASCII_UTF16 (default)
      Encode pure ASCII text data as ASCII, and encode all non-ASCII text data as UTF-16. Using this option adheres to the limitations of the id3v2.3 standard.
    • UTF16
      Encode all text frames using UTF-16 (big-endian, with BOM). Using this option adheres to the limitations of the id3v2.3 standard.
    • UTF16BE
      Encode all text frames using UTF-16BE encoding.
      Using this option requires that your media player supports the id3v2.4 standard for MP3 encoding.
    • UTF8
      Encode all text frames using UTF-8 encoding.
      Using this option requires that your media player supports the id3v2.4 standard for MP3 encoding. (Note however, that some tag editors use UTF-8 encoding as interchangable with ASCII encoding even though they are very different encodings. This is why your media player will often display text tags as meaningless garbage rather than the intended Russian, Chinese or Hindi, etc.)

    Media player hardware and software vendors have been slow to adopt the id3v2.4 standard, but if your media player does support the id3v2.4 version of the standard, then we recommend that this option be set for the technically superior UTF-8 text encoding which is the standard for all GNU/Linux systems and applications.

    Technically, the id3v2.3 specification indicates ISO-8859-1 (characters 20-FF hex) encoding rather than pure ASCII; however, ISO-8859-1 is used in less than five percent of servers and is almost never used in Linux systems. For this reason, Taggit will decode, (but not encode) ISO 8859-1 text tags which use the so-called “Latin-1” extension characters. This ensures that languages supported by ISO-8859-1 such as Spanish and German will be displayed correctly on all systems.

    (Please note that the ‘TextEncoding’ configuration option does not apply to OGG/Vorbis media files. OGG/Vorbis text tags, are always written using modern UTF-8 encoding.)


  9. Included Tag Fields
    This option determines which tag fields will be visible in the dialog window and are available for edit. Each item in this group may be set to either ‘true’ or ‘false’.
    If true, then the field will be displayed.
    Example: Enable_Title = true
    If false, then the field will be invisible.
    Example: Enable_RecordLabel = false

    If the configuration file is not found on startup, all fields will be enabled. If a field setting is not specified by the configuration file, that field will be enabled. The default configuration setting for each field is listed.

    • Enable_Title        (MP3 Tag: TIT2)   default: true
      Title/songname/content description
    • Enable_Artist       (MP3 Tag: TPE1)   default: true
      Lead performer(s)/Soloist(s)
    • Enable_Album        (MP3 Tag: TALB)   default: true
      Album/Movie/Show title
    • Enable_Track        (MP3 Tag: TRCK)   default: true
      Track number/Position in set
    • Enable_Year         (MP3 Tag: TYER)   default: true
      Year released
    • Enable_Genre        (MP3 Tag: TCON)   default: true
      Content type, Genre
    • Enable_GuestArtist  (MP3 Tag: TPE2)   default: true
      Band/orchestra/accompaniment
    • Enable_RecordLabel  (MP3 Tag: TPUB)   default: true
      Publisher
    • Enable_Composer     (MP3 Tag: TCOM)   default: true
      Composer(s)
    • Enable_Lyricist     (MP3 Tag: TEXT)   default: true
      Lyricist/Text writer(s)
    • Enable_RemixedBy    (MP3 Tag: TPE4)   default: true
      Interpreted, remixed, or otherwise modified by
    • Enable_Copyright    (MP3 Tag: TCOP)   default: true
      Copyright message
    • Enable_ContentOwner (MP3 Tag: TOWN)   default: false
      File owner/licensee
    • Enable_Comment      (MP3 Tag: TXXX)   default: true
      User defined text information frame
    • Enable_RecDate      (MP3 Tag: TDAT)   default: false
      Recording Date of the format: DDMM
    • Enable_RecTime      (MP3 Tag: TIME)   default: false
      Recording Time of the format: HHMM
    • Enable_DateSupp     (MP3 Tag: TRDA)   default: false
      Recording dates (additional date information)
    • Enable_Length       (MP3 Tag: TLEN)   default: true
      Length of audio playback in milliseconds
    • Enable_Size         (MP3 Tag: TSIZ)   default: true
      Size of audio file in bytes (excluding tag data)
    • Enable_BeatsPerMin  (MP3 Tag: TBPM)   default: false
      BPM (beats per minute)
    • Enable_ContentGroup (MP3 Tag: TIT1)   default: true
      Content group description, music classification or grouping
    • Enable_Subtitle     (MP3 Tag: TIT3)   default: true
      Subtitle/Description refinement
    • Enable_Conductor    (MP3 Tag: TPE3)   default: true
      Conductor/performer refinement
    • Enable_PartOfSet    (MP3 Tag: TPOS)   default: true
      Part of a set (disc number, episode, etc.)
    • Enable_InitialKey   (MP3 Tag: TKEY)   default: false
      Initial musical key in which the music was written
    • Enable_Language     (MP3 Tag: TLAN)   default: true
      Language(s) of the recording
    • Enable_OrigArtist   (MP3 Tag: TOPE)   default: true
      Original artist(s)/performer(s)
    • Enable_OrigAlbum    (MP3 Tag: TOAL)   default: true
      Original album/movie/show title
    • Enable_OrigFilename (MP3 Tag: TOFN)   default: true
      Original filename
    • Enable_OrigLyricist (MP3 Tag: TOLY)   default: true
      Original lyricist(s)/text writer(s)
    • Enable_OrigYear     (MP3 Tag: TORY)   default: true
      Original release year
    • Enable_NetStation   (MP3 Tag: TRSN)   default: true
      Internet radio station name
    • Enable_NetOwner     (MP3 Tag: TRSO)   default: true
      Internet radio station owner
    • Enable_ISRC_CODE    (MP3 Tag: TSRC)   default: false
      ISRC (international standard recording code), unique identifier
    • Enable_Settings     (MP3 Tag: TSEE)   default: false
      Software/Hardware and settings used for encoding
    • Enable_FileType     (MP3 Tag: TFLT)   default: false
      File type (MP3, OGG, WAV, etc.)
    • Enable_PlayDelay    (MP3 Tag: TDLY)   default: false
      Delay between end of playback and the beginning of next track
    • Enable_EncodedBy    (MP3 Tag: TENC)   default: false
      The person or company which encoded the audio data.
    • Enable_MediaType    (MP3 Tag: TMED)   default: false
      Media type (CD, DVD, tape, streaming, etc.)

    To override the configuration file’s field selections, see 'a' option to enable all text tag fields.

    All fields may also be enabled through 'Set All Fields Active' item in the ‘View Menu’.
    See Activate Fields, for additional information.




Next: , Previous: , Up: Top   [Contents][Index]

Building from Source

Tools

The Taggit application is written in C++ and is built with the GNU C++ compiler and linker.

Additional libraries and tools:

  1. The 'ncurses' development package. Your system installation may have included this package by default. If not, please visit:
    http://ftp.gnu.org/gnu/ncurses/
    for a list of stable releases.

    As of this writing (March 2017), we believe that v:6.0 for x86 is probably stable, but that other v:6.0 builds may still be rather unstable, and we recommend installation of the latest v:5.9 release available for your platform, OR build the v:6.0 source using the v:5 compatibility switch.

  2. The NcDialog API, available as a separate download from the author’s website. This builds to a link library (see below) which provides the dialog window and controls, along with other text-formatting tools.
  3. No additional link libraries or third-party tools are needed.

Compiling

  1. First, download and build the NcDialog API link library.
    For simplicity, install the NcDialog source at the same directory level as the Taggit source.
    Example: ~/SoftwareDesign/NcDialog ~/SoftwareDesign/Taggit

    Instructions for building the library are included with the NcDialog API package.

  2. When the NcDialog API library has been built successfully, go to the Taggit source directory and copy the necessary NcDialog files to the Taggit directory.

    Thia copy operation is built into the Makefile which uses the 'rsync' utility to refresh the needed files.

    gmake refreshlib

    If you did not install the source for the two packages at the same directory level, then the 'rsync' call will fail, and you will have to copy the needed files manually. Copy the following files:

    NcDialog/Dialog1/NcDialog.a /GlobalDef.hpp /NCurses.hpp /NCursesKeyDef.hpp /NcWindow.hpp /gString.hpp /NcDialog.hpp TO: Taggit
  3. Taggit is compiled using the GNU/G++ compiler which is invoked through the 'gmake' (‘make’) utility. The compile and linking instructions are contained in the file named 'Makefile'.
    Example: gmake clean (delete any existing binary and object files) gmake (build all modified components)

Build Options

No optional builds are currently defined.


Testing the Build

To test the build, invoke with a request for the Taggit version number. You should get something similar to the following:

./taggit --version Taggit - v:0.0.08 Copyright(c) 2016-2020 The Software Samurai ==================================================================== License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html> This is free software: you are free to modify and/or redistribute it under the terms set out in the license. There is NO WARRANTY, to the extent permitted by law.

Installation

For the taggit application to be visible throughout your system, you will need to copy the 'taggit' binary file, the default configuration file and the Help files to a directory on your execution path.

To see your execution path, type: echo $PATH.

[Taggit]$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:
/usr/sbin:/home/sam/.local/bin:/home/sam/bin

The directories searched for binaries are separated by the colon ':' character. Generally, it is recommended that you choose the last entry in the list because that directory belong only to you.

EXAMPLE:  cp --preserve taggit             /home/sam/bin/.
          cp --preserve taggit.cfg         /home/sam/bin/.
          cp --preserve taggit.info        /home/sam/bin/.
          cp --preserve taggit.html        /home/sam/bin/.
          cp --preserve infodoc-styles.css /home/sam/bin/.

Alternatively, symbolic links to these files (not including the style definitions) may be placed on the execution path:

EXAMPLE:
cp --symbolic-link ~/SoftwareDesign/Taggit/taggit      ~/bin
cp --symbolic-link ~/SoftwareDesign/Taggit/taggit.cfg  ~/bin
cp --symbolic-link ~/SoftwareDesign/Taggit/taggit.info ~/bin
cp --symbolic-link ~/SoftwareDesign/Taggit/taggit.html ~/bin

Note on temporary files: Taggit creates various temporary files during execution. Taggit queries the system for the directory where temporary files are to be created. If the specified directory cannot be found, then Taggit cannot scan the source files for metadata, and a diagnostic message will be displayed:

Taggit v:0.0.08 (c)2016-2020 The Software Samurai ------------------------------------------------- ERROR: Directory for creating temporary file is inaccessible.

For more information on temporary files, please see the documentation for the 'tmpnam_r' C-language function or the coreutils 'mktemp' utility.


Installing the Documentation

Documentation for Taggit is provided in both Texinfo (info) format and HTML format.

To view the HTML-format documentation, navigate to:
Taggit/Texinfo
then load the 'taggit.html' document into your favorite browser.
xdg-open taggit.html
Note that the 'infodoc-styles.css' CSS style definition file must be in the same directory as the HTML document.

To view the Texinfo (info) documentation, navigate to:
Taggit/Texinfo
then view the documentation using the following command:
info -f taggit.info

Follow these steps to install the Taggit documentation into the ’info’ database.

  1. Note that installing the documentation is not necessary, but is recommended. Not only is it convenient to have the documentation always available, but it is a useful skill for when you begin installing documentation for your own applications!
  2. Adding an ’info’ document to the info-reader database (or removing a document from the database) is easy, but it does require ’SUPERUSER’ (’root’) user privilege. If this makes you nervous, please make a backup copy of the ’dir’ (info database) file before modifying it.
  3. Open a terminal window.
  4. Navigate to the directory which contains the ’taggit.info’ documentation.
    Example: cd ~/MySoftware/Taggit/Texinfo (substitute your actual installation path)
  5. Locate the master Info system directory file: ’dir’.

    sudo find /usr/local -name dir

    For local users, this is typically:
    /usr/local/share/info/dir
    For multi-user systems, this is typically:
    /usr/share/info/dir

  6. Copy the document to the directory where you found the info ’dir’ file.
    Example: sudo cp --preserve=timestamps taggit.info /usr/local/share/info/. (substitute the actual path to the directory containing the 'dir' file) Enter your password when prompted.
  7. Navigate to the Info target directory.
    cd /usr/local/share/info
  8. Verify that the document was copied correctly.
    ls -l taggit.info
  9. Add the menu entry.
    sudo install-info --dir-file=dir --info-file=taggit.info --name=’Taggit Metadata Editor’ --debug Note that this is a single command, typed all on one line even though it may look strange as printed here. Enter your password when prompted.
  10. Verify the install.
    Type the following command: info

    This will open the top-level menu of the Info system.
    Verify that your new entry is beautifully displayed and that the new Info document is accessible:

    First, press the forward-slash key ’/’ (search)
    Then, type: Taggit (and press ENTER)
    The highlight should now be on the menu entry.
    Press ENTER (RET) key again, and verify that the main page of the Taggit documentation is displayed.
    Then, exit the Info system: ’q’ (quit).

  11. If the menu item is not present OR if the new Info document is not accessible, then try the installation again.

    If you want to remove the menu entry, use the command:

    sudo install-info --dir-file=dir --info-file=taggit.info --name=’Taggit Metadata Editor’ --remove --debug Again, this is a single command, typed all on one line. Enter your password when prompted.



Next: , Previous: , Up: Top   [Contents][Index]

Tech Notes

Editorial: Software Sam sincerely dislikes working with proprietary standards: MPEG, SBC, WMA (or anything containing the word ‘Microsoft’), and on and on...

Still, neither the artists who create music nor the billions of people who enjoy listening to music are to blame for these proprietary standards, so remember: Pirates are punks – pay a fair price for the pleasure that music brings.

“She Works Hard For the Money, so you’d better treat her right.”
      — Donna Summer


Format Standards

The current release of this application supports three(3) audio formats:

MP3 for better or worse, the audio industry standard OGG/Vorbis the next generation of open-standards audio WMA Windows(tm) Media Audio (ASF media container)

The MP3 Standard

The de facto industry standard and by far the most widely used music format (except for the Apple(tm) bonkers in the crowd) is the MPEG-1/MPEG-2 Audio Layer III ("MP3") format. This group of standards has suffered from organic (rather than planned) growth over the years. As such, it is in our opinion a mass of half-baked ideas marinated in a stew of corporate greed. In other words, it is a proprietary and patented format, although the standard has long ago been illegally released to the general public. The good news is that all known patents will have expired by the end of the year 2017; although copyrights are still in effect for individual works of audio art.

The metadata (tag data) is stored in the MP3 data stream using the ID3v2 standard in its various versions. This application uses the ID3v2.3.0 version, with some support for ID3v2.4 text tags including UTF-16BE and UTF-8 text encoding.


The OGG/Vorbis Standard

For the socially conscious enthusiast and the perversly independent music lover, the OGG/Vorbis format is available as an open standard container and audio data stream format. It is released by the Xiph.Org Foundation.

Metadata (tag data) for OGG/Vorbis audio is clean and simple, requiring no special knowledge beyond the standards documents. Note however that these documents were written by engineers, NOT by masters of the written word. As such, the explanations are ambiguous and can be rather confusing and frustrating. Fortunately, OGG/Vorbis tag-data formatting is so simple, that looking at a few example files is generally enough for full understanding.


The ASF (WMA) Standard

The Microsoft(tm) “Advanced Systems Format” is a media container which is commonly used for music download, streaming and other digital media applications. The media most often encapsulated within the ASF container are Windows(tm) Media Audio (WMA) and Windows Media Video (WMV).

https://www.loc.gov/preservation/digital/formats/fdd/fdd000067.shtml
https://docs.microsoft.com/en-us/windows/win32/wmformat/overview-of-the-asf-format

Important Note: Although the ASF standard is publicly documented, the actual use of the standard and the patented algorithm used to implement the standard is strictly controlled under license to Microsoft. As such, ASF and WMA represent the antithesis of everything the GNU/Linux community stands for.

The Taggit application’s support for viewing metadata in WMA audio files is based basic research and on sample WMA files distributed with the Windows Vista(tm) operating system. The proprietary Microsoft algorithm was not referenced in any way.

Unfortunately,even a mere discussion of the contents of the ASF standard itself may be considered as copyright infringement. We sincerely apologize, but we are unable to provide details of this specification in this document. Instead, we describe in general terms the types and amount of metadata that may be included in within the ASF media container.
(Please direct all complaints to Satya Nadella, Microsoft Corporation, Redmond WA.)

For a real-world example of this distopian morass, please see the story of audio software developer, Avery Lee, author of “VirtualDub”. This article is posted on the WaybackMachine:
https://web.archive.org/web/20170628194627/http://www.advogato.org/article/101.html




Headers

MP3 Headers

Tag Header

The Tag Header begins every MP3 file, and identifies the file.

A valid ID3 tag header will be of the form:
I D 3 mm rr ff nn nn nn nn

'ID3' three-character string literal 'mm' major ID3 version (< FFh) 'rr' minor ID3 revision (< FFh) 'ff' flag byte 'nn nn nn nn' is the integer number of bytes in the Tag. encoded as four, 7-bit bytes, MSB first Example: 2200 decimal (0x00000898) would be encoded as: 00 00 11 18

Extended Header

The “Extended Header” is optional, and if present is of the form:
ss ss ss ss ff ff pp pp pp pp cc cc cc cc

'ss ss ss ss' integer (big-endian) indicating size of header, currently six(6) bytes without CRC or ten(10) bytes with CRC) 'ff ff' sixteen flag bits MSB first 'pp pp pp pp' integer (big-endian) indicating number of padding bytes allocated 'cc cc cc cc' (optional), if specified: integer (big-endian) CRC error detection value

Technical Note: Because the Extended Header is defined as “optional,” most encoders will omit it even when it is actually necessary to indicate the number of padding bytes. This inexcusable encoding error causes a parsing error at the beginning of the padding area, so encountering an invalid frame header in the input stream must be assumed to indicate the beginning of the padding area. (These people should not be allowed anywhere near a computer.)
Most media players not only do not encode the Extended Header when appropriate, the media players are generally unable to decode it as part of the MP3 tag data, which results in tag decoding errors.

Tag Footer

The Tag Footer is a convenient way of finding the tag data when the search begins at the end of the file. Note that if a Tag Footer is present, then a padding area is not allowed.

The Tag Footer contains the same information as the Tag Header except that it has a different identifier string: “3DI” versus “ID3”. The Tag Footer is defined as part of the id3v2.4 standard and may not be recognized by id3v2.3 hardware/software.

A valid ID3 tag footer will be of the form:
3 D I mm rr ff nn nn nn nn

'3DI' three-character string literal 'mm' major ID3 version (< FFh) 'rr' minor ID3 revision (< FFh) 'ff' flag byte 'nn nn nn nn' is the integer number of bytes in the Tag. encoded as four, 7-bit bytes, MSB first Example: 2200 decimal (0x00000898) would be encoded as: 00 00 11 18

Frame Header

The id3v2 specification defines a large number of “Frame Types” which provide many different kinds of configuration and setup information for the audio playback hardware or software.

Any reasonable number of “Frames” may be included in the MP3 Tag. A valid Frame ID is one of the defined, four-character ASCII strings, with the first character between 'A' and 'Z' or between '0' and '9'.

A valid Frame Header will be of the form:
cccc ss ss ss ss ff ff

'cccc' four-character string literal 'ss ss ss ss' integer frame size in bytes (not incl. header itself) (this is a big-endian value) 'ff ff' flags (two bytes)

Up to six(6) bytes of additional information may be appended to the Frame Header depending on whether the compression flag, the encryption flag or the group flag is set. These flags are seldom used, and almost never used for Text frames — but if they are, the size of the appended data is not included in the header size, but is included in the frame size.

Taggit is interested primarily in the Text Frames, i.e. frames that contain human-readable text data. Text frames begin with the letter 'T', followed by three(3) additional characters. Examples would be TCOP, TIT1, TIT2, TRCK and TXXX. Each of these Frame IDs corresponds to one of the column headings in the Taggit application’s Field Edit window. (see types of metadata for a complete list)

Text Frame

A Text Frame begins with a single byte which indicates the type of text encoding.

Taggit supports all these text encodings; however, your media player may not be able to decode the UTF-16BE and UTF-8 encodings correctly because the id3v2.4 standard has not yet been embraced by the mainstream audio hardware/software.

Following the encoding type, is the text data which may or may not be null terminated. [‘frame size’ minus one, (fs-1)] is the number of bytes in the text array. (The exception would be if compression, encryption or the group flag were set as described above.)

Obsolete ID3V1 Tag

The early MP3 format (id3v1) defined a 128-byte tag block at the end of the audio file. This obsolete construction is incompatible with the newer versions of the standard. Thus, if Taggit encounters this obsolete block while writing the edited metadata to the target file, the block will be silently deleted.


OGG/Vorbis Headers

The OGG/Vorbis standard defines three(3) header records, all of which must be present in order for the audio data to be properly decoded for playback.

  1. Identification Header (Page 1)
    Fifty-eight (58) bytes which identify the file as OGG/Vorbis audio.
  2. Comment Header (Page 2a)
    A list of comment tags, known as “Comment Vectors” in OGG/Vorbis world. The standard allows 2^32-1 comment vectors and each vector may be up to 2^32-1 bytes in length. However, in practice, there will probably be less than thirty (30) comment vectors, and the standard states that each vector “isn’t going to be more than a short paragraph.
    More extensive text data would not be placed in a comment vector, but would be embedded as a separate XML stream.
  3. Setup Header (Page 2b)
    The Setup Header contains technical information for codec configuration. The actual data contained in the Setup Header and how it is formatted is beyond the scope of this document. Taggit simply copies these data as a block without decoding it. See the Xiph.org website for more information.
    <https://xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-650004.2.4>

Identification Header

The Identification Header is the only data in Page 1 of an OGG/Vorbis audio file, and takes the form:
OggS vv ht gg gg gg gg gg gg gg gg ss ss ss ss
pp pp pp pp cc cc cc cc sc st pt vorbis vv vv vv vv
ac sr sr sr sr bx bx bx bx bn bn bn bn bm bm bm bm bs fb

'OggS' 4-character string identifying the page 'vv' 8-bit stream structure version number (always 00h) 'ht' 8-bit header type (always 02h i.e. begin stream) 'gg' 64-bit integer (little-endian) granpos (always zero) 'ss' 32-bit integer (little-endian) stream serial number 'pp' 32-bit integer (little-endian) page sequence number (zero) 'cc' 32-bit integer (little-endian) CRC (checksum) value for page 'sc' 8-bit integer, “segments” defined (always 01h) 'st' segment table, always one entry (1Eh) 'pt' packet type, 01h, Identification Header 'vorbis' 6-byte string literal (case insensitive and not null terminated) 'vv' 32-bit integer (little-endian) vorbis version number (zero) 'ac' vorbis version number (always zero) 'sr' 32-bit integer (little-endian) sample rate 'bx' 32-bit integer (little-endian) bitrate (maximum value) 'bn' 32-bit integer (little-endian) bitrate (nominal value) 'bm' 32-bit integer (little-endian) bitrate (minimum value) 'bs' 8-bit block size 4 MSb's == blksize0, 4 LSb's == blksize1 'fb' framing bit (always 01h)

Taggit does not modify the Identification Header in any way.


Page 2 - Comment Header and Setup Header

‘Page 2’ of the file contains both the Comment Header and the Setup Header. Note that the specification allows the data for these headers to extend into Page 3; however, this is unlikely because Page 2 can hold approximately 255x255 or 65,025 bytes plus overhead. In comparison, of the OGG/Vorbis files we have examined, the largest Page 2 we have seen is less than eight(8) KBytes. The exception would be if the file included a very large embedded image or multiple images.

Page 2 begins with a twenty-seven(27) byte page header of the form: OggS vv ff gg gg gg gg gg gg gg gg ss ss ss ss pp pp pp pp
cc cc cc cc sc

'OggS' 4-character string identifying the page 'vv' 8-bit stream structure version number (always 00h) 'ff' 8-bit flag byte (only 3 LSb's are defined at this time) 'gg' 64-bit integer (little-endian) absolute granule position 'ss' 32-bit integer (little-endian) stream serial number 'pp' 32-bit integer (little-endian) page sequence number 'cc' 32-bit integer (little-endian) CRC (checksum) value for page 'sc' 8-bit integer, number of “segments” defined

Following the page header is a table of “segments”. The table is an array of 8-bit values with each table entry between 0-255 (00h - FFh). The number of table elements is the ‘segment count’ as specified in the page header.

The comment data and setup data are positioned in the “segments’ which follow the segment table.

Immediately following the segment table is the “Packet Header”. The Packet Header is a seven-byte record of the form:
tt vorbis

'tt' 8-bit packet type code 01h indicates the Identification Header 03h indicates the Comment Header 05h indicates the Setup Header 'vorbis' 6-byte string literal (case insensitive and not null terminated)

Following the Packet Header is a specialized Comment Vector which contains the “Vendor Record.” A Vendor Record will be similar, but not identical to the following: “Xiph.Org libVorbis I 20020717”

The Vendor Record is followed by a 32-bit (little-endian) integer value indicating the number of Comment Vectors which follow, with a zero value indicating that no Comment Vectors are defined.


Comment Vector

A Comment Vector consists of two parts and takes the form:
cc cc cc cc [uu uu ....]

'cc cc cc cc' 32-bit (little-endian) integer indicating the number of bytes in the comment string 'uu uu .... ' zero or more bytes of UTF-8-encoded text data (see below)

The text data for a Comment Vector is the number of bytes specified and is in three parts of the form: COMMENT_NAME=COMMENT_TEXT

  1. Comment Name
    This is an ASCII (7-bit characters) string which is the name of the comment field. This is a case-insensitive character sequence with each character being between 20h (space character) and 7Dh (right curly bracket character), inclusive, but excluding '=' (3Dh).

    The Comment Name may be any character sequence which follows the stated criteria; however, Xiph.org recommends that “vendors should make some effort to avoid arbitrarily polluting the common namespace.” See ogg/vorbis text tags, for a list of defined Comment Names.

    Comment Names need not be unique within a file, and in fact Xiph.org encourages placement of each comment into a separate Comment Vector.

  2. Comment Separator (an EQUALS sign '=' 3Dh)
    This character separates the comment name from the comment itself.
  3. Comment Text
    The remainder of the comment is a standard UTF-8-encoded text string, but the text is not null terminated.

The Comment Vector array is terminated by a “Framing Bit” which is actually an 8-bit value with only the LSB set: 01h.


Setup Header

Following the array of Comment Vectors, is the Setup Header.

The Setup Header fills out the remainder of Page 2, and consists of codebook configurations, time-domain transform configurations, floors, residues, mappings and modes.

Taggit does not decode or modify the Setup Header.

Page 2 is terminated by a “Framing Bit” which is actually an 8-bit value with only the LSB set: 01h, and is the last byte of the last segment in Page 2. If the Framing Bit is not found where it should be, then the page cannot be reliably decoded.

Immediately after the Setup Header, the audio data streams begins.


ASF (WMA) Headers

The ASF specification defines five(5) header objects which can contain metadata, but only two of these are commonly used to contain human-readable text information and images such as cover art.

A third header-object type may contain a specialized kind of image used only for advertizing purposes, (e.g. a copyright warning). The contents of this object are not examined by this application, and the object is simply copied unmodified from source to target.

Two additional types of header objects may contain human-readable metadata, but these are seldom used. The contents of these objects are currently not examined by this application, and the objects are simply copied unmodified from source to target.





Types of Metadata

MP3 Text Tags

Editing of all MP3 Text Tags is fully supported by Taggit:

 TIT2  Title/songname/content description
 TPE1  Artist/Lead performer(s)/Soloist(s)
 TALB  Album/Movie/Show title
 TRCK  Track number/(and optionally, track count)
 TYER  Year (4-character field: "YYYY")
 TCON  Content type (genre), one of the defined codes OR freeform
 TPE2  Guest artist/band/orchestra/accompaniment
 TPUB  Publisher, record label
 TCOM  Composer(s) (separated by the '/' character)
 TEXT  Lyricist/Text writer
 TPE4  Interpreted, remixed, or otherwise modified by
 TCOP  Copyright message (first 5 chars: "YYYY " + any additional info)
        When displayed: "Copyright © YYYY nnnnnn..."
 TOWN  File owner/licensee
 TXXX  User defined text information frame
 TDAT  Date of the recording (4-character field: "DDMM")
 TIME  Time (4-character field: "HHMM")
 TRDA  Recording dates
 TLEN  Length (numeric string: play length of audio in milliseconds)
 TSIZ  Size (numeric string: size of audio in bytes, excl. metadata)
 TBPM  BPM (beats per minute)
 TIT1  Content group description
 TIT3  Subtitle/Description refinement
 TPE3  Conductor/performer refinement
 TPOS  Part of a set
 TKEY  Initial key
 TLAN  Language(s)
 TOPE  Original artist(s)/performer(s)
 TOAL  Original album/movie/show title
 TOFN  Original filename
 TOLY  Original lyricist(s)/text writer(s)
 TORY  Original release year
 TRSN  Internet radio station name
 TRSO  Internet radio station owner
 TSRC  ISRC (international standard recording code)
 TSEE  Software/Hardware and settings used for encoding
 TFLT  File type (MPG /1 /2 /3 /2.5 /AAC VQF PCM)
 TDLY  Playlist delay (numeric string: Milliseconds delay between songs)
 TENC  Encoded by
 TMED  Media type (DIG ANA CD LD TT TV RAD, etc.)

MP3 Embedded Image

The 'APIC' tag is provided for embedding cover art or similar images.
There are certain limitations on the type of image used. The image will be in either JPEG or PNG format with a practical size limit of approximately ten (10) kilobtes per image.

The audio file may contain multiple image frames provided that the description for each image is unique, however there may be only one file-icon image specified.

The image tag frame consists of the following fields.


MP3 Other Tag Types

Certain other non-text tags may be of interest to the user:

POPM  This is a "Popularity Meter" which is encoded as an integer value
      between 1 and 255 (a zero value indicates that the tag is unused).
      Media players usually display this value as a number of 'stars' 
      between 1 and 5 stars. There is no established standard for the way
      this field is interpreted, so its value is generally unreliable.

PCNT  This is a "Play Count" tag which may be updated by some media
      players to indicate how many times the song has been played.

Please see Popularimeter for more information on how these tag fields are used.


OGG/Vorbis Text Tags

The OGG/Vorbis standard defines the following Text Tags:
(This list is posted on the XiphWiki page: xiph.org.)

OGG NAME MP3 EQUIVALENT
- - - - - - - - - - - - -

 TITLE           TIT2 - Title
 ARTIST          TPE1 - Artist
 ALBUM           TALB - Album
 TRACKNUMBER     TRCK - Track
 GENRE           TCON - Genre "(nn) xxx..."
 PERFORMER       TPE2 - Guest Artist
 ORGANIZATION    TPUB - Publisher, Record Label
 VERSION         TPE4 - Remixed By
 COPYRIGHT       TCOP - Copyright "YYYY xxx..."
 LICENSE         TOWN - Owner/Licensee
 DESCRIPTION     TXXX - Freeform comment
 DATE            TRDA - Freeform recording date(s)
 CONTACT         TRSN - Contact: 'Internet radio station name'
 LOCATION        TENC - Settings for encoding (location, studio)
 ISRC            TSRC - ISRC recording code

Additional (non-standard) Text Tags are in common use:

 COMPOSER        TCOM - Composer
 TRACKTOTAL      TRCK - Number of tracks (complements TRACKNUMBER)
                        (under MP3: trk/tot)
 DISCNUMBER      TPOS - Sequence number of disc in set
                        (combine with "DISCTOTAL": dscnum/dsctot)
 DISCTOTAL       TPOS - Total number of discs in set
 ENCODER         TENC - Encoded-by
 SOURCEMEDIA     TMED - Media type
 PRODUCTNUMBER   UFID - (unique file identifier, for database searches)
 RATING          POPM - Popularity rating (1-5 stars)

OGG/Vorbis Embedded Images

Important Note: While Taggit fully supports OGG/Vorbis embedded images, many media players do not correctly decode them, either ignoring them or handling them incorrectly so that the audio becomes unplayable. Therefore, caution is recommended when embedding images into OGG/Vorbis audio files. Try creating a test file to determine whether your favorite media player can correctly decode and play the audio.

To increase the chance of success it is STRONGLY RECOMMENDED that the combined total size of all images be limited to no more than fifty(50) kilobytes.


The OGG/Vorbis tag standard has only recently (mid-2016) defined support for embedded images. Consequently, many software audio players and most hardware players are unable to render these images and may be unable to play audio files which contain these images.

Images may be embedded into an OGG/Vorbis audio file in a way that is similar, but not identical to the method used in the id3v2 standard ('APIC' frame). This similarity is intentional, and allows software and hardware audio players to be easily adapted to decode and display images stored in the OGG container.

Image encoding uses the “FLAC” (Free Lossless Audio Codec) header format. FLAC is also maintained by Xiph.org, creators of the OGG/Vorbis standard.

The binary image data are encoded using the ancient “Base64” algorithm which was created to allow transmission of binary data across networks designed for 7-bit data streams (i.e. UNIX). This is done by converting each six(6) bits of binary data into a 7-bit ASCII character (MSB is always zero).

Of course, in the modern world, nearly every digital stream is what nerds call 8-bit clean, meaning that the network can correctly handle any 8-bit binary stream. This means that the Base64 format, which is huge and decidedly inefficient, is actually no longer necessary. However the folks at Xiph.org decided to use it for OGG/Vorbis embedded images.

Their logic seems to be that it allows the use of the OGG Comment structure (see above) by converting the binary data to ASCII pseudotext. While this works (sort of), it is a classic case of “If it was good enough fer my grandpa, it’s good enough fer me.”. Actually, this decision violates the spirit of their own standard which states that an OGG Comment “isn’t going to be more than a short paragraph.”. In addition, some of the data contained in the vector is integer data, not text, so an audio player expecting a UTF-8 comment could get a pile of garbage instead.

Both JPEG (Joint Photographic Experts Group) and PNG (Portable Network Graphics) images may be used. Other image formats may not be embedded into the audio file but may be indicated via a URL to an external image.

(It should be noted that external images are discouraged due to a high probability that the audio file and its images will become separated. Even if the image is visible to the player, the embedded URL may cause an unexpected network fetch, which on a pay-by-the-megabyte phone plan could become expensive. For these reasons, Taggit does not support URL-referenced images at this time.)

A Comment Vector (described above) is modified to include not only the encoded binary image, but also certain setup data and a short comment describing the image.

This Image Vector (our terminology) consists of fourteen(14) parts. The first three(3) parts follow the standard Comment Vector format, while the remaining parts are unique to the Image Vector. An Image Vector takes the form:

cc cc cc cc METADATA_BLOCK_PICTURE = tt tt tt tt mm mm mm mm [MM MM ....] ll ll ll ll [dd dd ....] ww ww ww ww hh hh hh hh bb bb bb bb ii ii ii ii LL LL LL LL [pp pp ....] 'cc cc cc cc' 32-bit (little-endian) integer indicating the total number of bytes in the image vector 'METADATA_BLOCK_PICTURE' Image Vector name (22 bytes) This is an unterminates ASCII string. '=' 'Equals' character delimits the comment name from the comment data. 'tt tt tt tt' 32-bit (big-endian) integer indicating the 'picture type'. This is adapted from the id3v2 list of 8-bit codes (see Picture Type) denoting what the image represents. 'mm mm mm mm' 32-bit (big-endian) integer indicating the length of the MIME-type string 'MM MM .... ' the ASCII "MIME Type" (Multipurpose Internet Mail Extensions) which is one of the following: "image/jpeg", "image/png" or if type is unknown, "image/" A link to an external image file is indicated by a leading "-->". 'll ll ll ll' 32-bit (big-endian) integer indicating the length of the description string in bytes 'dd dd .... ' zero or more bytes of UTF-8-encoded text data describing the image 'ww ww ww ww' 32-bit (big-endian) integer indicating the width of the image in pixels. (informational only, always set to zero) 'hh hh hh hh' 32-bit (big-endian) integer indicating the height of the image in pixels. (informational only, always set to zero) 'bb bb bb bb' 32-bit (big-endian) integer indicating the color depth in bits-per pixel. (informational only, always set to zero) 'ii ii ii ii' 32-bit (big-endian) integer indicating the color indexing. Note that JPEG and PNG images are not indexed so this is always set to zero. 'LL LL LL LL' 32-bit (big-endian) integer indicating the size of the encoded binary data in bytes. For externally linked files, this is zero indicating that no binary image data follows. 'pp pp .... ' binary image data encoded in the Base64 pseudotext format. While the data may technically be of any size up to the limit of a 32-bit integer, a more practical size would be between one(1) and ten(10) KBytes, and 50 KBytes would likely make the audio file unplayable because the Comment Header would then cross a page boundary causing many players to die a horrible death.

Technical Note: The values for image height, width, color-depth and indexing are informational only, and may be used by image editing applications such as Gimp for image rendering. These values are not used by media players, so we have made the design decision to always output the default value (0) for these parameters.


Early (non-standard) Image Encoding

Several years ago, a group of developers (AudioShell and others) independently implemented a format for embedding images into OGG/Vorbis audio files. This was an OGG Comment labelled as “COVERART”. While this implementation enjoyed some success, it is incompatible with the standard described. If 'Taggit' encounters one of these non-standard images, it will convert the data to standard format.

Programmer’s Note: Decoding and encoding “Base64” pseudo text is not as difficult as the MIME reference algorithm would indicate. Please see our Ogg_Image class definition for a more reasonable decode/encode algorithm which should work even on 8-bit microcontrollers.


OGG/Vorbis Other Tag Types

The OGG/Vorbis standard defines the “Setup Header” for setup/configuration purposes, while the MP3 standard uses a series of non-text tags.

Taggit simply copies the Setup Header from source to target without modification in order to maintain data integrity.


ASF (WMA) Text Tags

Within the two header objects that may contain text and image data, there are five fixed-name text-tag fields and a variable number of user-defined tag fields. The fixed-name fields are:

Title The title of the audio work
Author The author of the work (artist)
Copyright Copyright notice
Description General comment field
Rating Popularity rating

The correspondence between ASF tag names and the mainstream (MPEG-3) tag names used by this application is not obvious. Because most ASF tag names are defined by the encoder or playback application, certain design decisions were made to map the ASF tag names to the application’s display field.

If the tag name and the display-field names are identical or very similar, the mapping is straightforward. Otherwise, the application will compare the tag name with a list of key substrings in an attempt to achieve a match. In the case of multiple tag names which match a given substring, the value of the first matching instance will be displayed into the corresponding display field. Second and subsequent matches will be placed in the miscellaneous-tag field as described below.

Note that in practice, there is often some overlap and/or ambiguity between the fixed-name fields and the user-defined fields. For example, the contents of the fixed-name “Author” field is often identical to the contents of the “WM/AlbumAuthor” field. This is what happens when software designers drink Red Bull by the liter.


ASF Tag Fields

One compilation of possible tag names for ASF media can be found at:
https://exiftool.org/TagNames/ASF.html
Only the most common subset of these tags is listed here.

The tag names may be defined with or without the "WM/" prefix, which seems to be an integral part of the Window(tm) Media player, and by extension, the patented encoding tools.


ASF/WMA NAME MP3 EQUIVALENT
- - - - - - - - - - - - - - -

Title                   TIT2 - Title
Author                  TPE1 - Artist
WM/AlbumArtist          TPE1 - Artist
WM/AlbumTitle           TALB - Album
WM/TrackNumber          TRCK - Track
WM/Track                TRCK - Track
WM/Year                 TYER - Year
WM/Genre                TCON - Genre
WM/ProviderStyle        TCON - Genre
Copyright               TCOP - Copyright
Description             TXXX - Comment
WM/Composer             TCOM - Composer
WM/Publisher            TPUB - Publisher, Record Label
WM/Provider             TOWN - File Owner/Licensee
WM/AudioFileURL         TRSO - Internet Radio Station Owner
WM/AudioSourceURL       TRSN - Internet Radio Station Name
WM/Lyrics               TOLY - Original Lyricist
WM/EncodingTime         TLEN - Playback Time (mSec)
WM/UniqueFileIdentifier TOFN - Original Filename
RemixedBy               TPE4 - Interpreted/Remixed By
AudioLength             TLEN - Audio Data Size (bytes)
Rating                  (data stored in Popularimeter)
WM/ProviderRating       (data stored in Popularimeter)
WM/Picture              (data stored in separate image file)

Display of Miscellaneous Tag Fields

Tag names for which the application cannot determine a direct match to a display field: The tag-name/tag-value pair are concatenated as a single, delimited display value. This concatenated list is displayed in the “File Type” field. (This is an MPEG-3 field which is not used by WMA audio files.)

Example of data displayed in this field:
Delimeters are the Chinese characters:
名 "name"
值 "value"
These delimeters were chosen because they are visually easy to identify, and because they are unlikely to be characters in the tag text.

名Track值10 名MediaPrimaryClassID值{D1607DBC-E32 3-4BE2-86A1-48A42A28441E} 名WMFSDKVersion值11.0. 5705.5043 名WMFSDKNeeded值0.0.0.0000 名IsVBR值0 名UniqueFileIdentifier值AMGa_id=R 735600;AMGp_id=P 698887;AMGt_id=T 7666401 名AlbumArtist值Katy Perry名MCDI值MCDI 名ProviderRating值2 名ProviderStyle值Rock

This field may be manually edited so long as the delimiters for each name/value pair remain intact. When written to target, each name/value pair will be written as a separate tag.


ASF Embedded Images

One or more of the user-defined tag fields described in the above table may contain an image. This is determined by the tag name, “Picture,”, “Image,”, etc. and by the fact that the value field contains binary data.
The image could technically be of any type, but for reasons of compatibility only JPEG images should be used. The maximum size of an image is 64KiB (65,535 bytes) minus approximately forty(40) bytes for setup information.


ASF Other Tag Types

Among the user-defined tag fields, the type of data contained in the field may be text, numeric or binary data.




Next: , Previous: , Up: Top   [Contents][Index]

Technical Support

Please Note: All trademarks and service marks mentioned in this document are the entirely-too-proprietary property of their respective owners, and this author makes no representation of affiliation with or ownership of any of the damned things.

Contact

Taggit (taggit) binary, source code and associated Texinfo documentation were written and are maintained by: Mahlon R. Smith, The Software Samurai Beijing University of Technology on the web at: www.SoftwareSam.us For bugs, suggestions, periodic updates, or possible praise, please post a message to the author via website. If possible, please include a copy of the Tech Support Request form. See Tech Support Request. The author wishes to thank everyone for their intelligent, kind and thoughtful responses. (ranters I can live without)

By the same author






Next: , Previous: , Up: Top   [Contents][Index]

Copyright Notice

The Taggit binary and source code are released under the GNU General Public License (GPL 3+), and the user documentation (this document) is released under the GNU Free Documentation License (FDL 1.3+):

Copyright © 2016-2020 Mahlon R. Smith, The Software Samurai This manual describes version 0.0.08 of ’taggit’. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Next: , Up: Copyright Notice   [Contents][Index]

GNU General Public License

Version 3, 29 June 2007

Copyright © 2007 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The GNU General Public License is a free, copyleft license for software and other kinds of works.

The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program—to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.

For the developers’ and authors’ protection, the GPL clearly explains that there is no warranty for this free software. For both users’ and authors’ sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.

Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users’ freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.

Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS

  1. Definitions.

    “This License” refers to version 3 of the GNU General Public License.

    “Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

    “The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.

    To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.

    A “covered work” means either the unmodified Program or a work based on the Program.

    To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.

    To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.

    An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

  2. Source Code.

    The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.

    A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

    The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

    The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.

    The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.

    The Corresponding Source for a work in source code form is that same work.

  3. Basic Permissions.

    All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

    You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

    Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.

  4. Protecting Users’ Legal Rights From Anti-Circumvention Law.

    No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

    When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.

  5. Conveying Verbatim Copies.

    You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

    You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.

  6. Conveying Modified Source Versions.

    You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:

    1. The work must carry prominent notices stating that you modified it, and giving a relevant date.
    2. The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
    3. You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
    4. If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.

    A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

  7. Conveying Non-Source Forms.

    You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:

    1. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
    2. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
    3. Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
    4. Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
    5. Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.

    A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.

    “Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.

    If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).

    The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.

  8. Additional Terms.

    “Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:

    1. Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
    2. Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
    3. Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
    4. Limiting the use for publicity purposes of names of licensors or authors of the material; or
    5. Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
    6. Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.

    All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.

    If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.

    Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.

  9. Termination.

    You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.

  10. Acceptance Not Required for Having Copies.

    You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.

  11. Automatic Licensing of Downstream Recipients.

    Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

    An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

    You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.

  12. Patents.

    A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.

    A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

    Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

    In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.

    If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.

    If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.

    A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.

    Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.

  13. No Surrender of Others’ Freedom.

    If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.

  14. Use with the GNU Affero General Public License.

    Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.

  15. Revised Versions of this License.

    The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.

    If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

    Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.

  16. Disclaimer of Warranty.

    THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  17. Limitation of Liability.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

  18. Interpretation of Sections 15 and 16.

    If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does. Copyright (C) year name of author This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

program Copyright (C) year name of author This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’. This is free software, and you are welcome to redistribute it under certain conditions; type ‘show c’ for details.

The hypothetical commands ‘show w’ and ‘show c’ should show the appropriate parts of the General Public License. Of course, your program’s commands might be different; for a GUI interface, you would use an “about box”.

You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see https://www.gnu.org/licenses/.

The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read https://www.gnu.org/licenses/why-not-lgpl.html.


Previous: , Up: Copyright Notice   [Contents][Index]

GNU Free Documentation License

Version 1.3, 3 November 2008

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copies of the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Previous: , Up: Top   [Contents][Index]

Index

Jump to:   0  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   R   S   T   U   V  
Index Entry  Section

0
01.0 Introduction: Introduction
02.0 Operational Overview: Operational Overview
03.0 Invoking: Invoking
04.0 User Interface: User Interface
04.1 User Interface Basics: User Interface Basics
04.1.1 Application Layout: Application Layout
04.1.2 Dialog Dimensions: Dialog Dimensions
04.1.3 Navigation: Navigation
04.1.4 Dialog Controls: Dialog Controls
04.2 Menus: Menus
04.2.1 Menu Access: Menu Access
04.2.2 File Menu: File Menu
04.2.3 Edit Menu: Edit Menu
04.2.4 View Menu: View Menu
04.2.5 Help Menu: Help Menu
04.2.6 Sort-by Submenu: Sort-by Submenu
04.3 Editing the Filename: Editing the Filename
04.4 Editing the Metadata: Editing the Metadata
04.5 UI Languages: UI Languages
05.0 Configuration: Configuration
06.0 Building from Source: Building from Source
07.0 Tech Notes: Tech Notes
08.0 Technical Support: Technical Support
09.0 Copyright Notice: Copyright Notice
09.1 GNU General Public License: GNU General Public License
09.2 GNU Free Documentation License: GNU Free Documentation License

A
a option: Invoking
active tag fields: View Menu
add image: Edit Menu
album option: Invoking
application colors: View Menu
application dialog: Operational Overview
application layout: Application Layout
artist option: Invoking
ASF (WMA) Headers: Tech Notes
ASF (WMA) standard: Tech Notes
ASF metadata: Tech Notes

B
build options: Building from Source
by the same author: Technical Support

C
c option: Invoking
C option: Invoking
change indicators: Application Layout
characters, special: Invoking
colors, application: View Menu
command-line arguments: Invoking
compile from source: Building from Source
configuration file: Configuration
contact info: Technical Support
control, list: Dialog Controls
control, menu: Dialog Controls
control, pushbutton: Dialog Controls
control, radiobutton: Dialog Controls
control, spinner: Dialog Controls
control, textbox: Dialog Controls
controls, dialog: Dialog Controls
counter, playback: Edit Menu

D
d option: Invoking
D option: Invoking
dialog controls: Dialog Controls
dialog dimensions: Dialog Dimensions
dialog layout: Application Layout
dialog screenshot: Operational Overview
dialog, save-files: File Menu
dimensions, dialog: Dialog Dimensions
disk space available: View Menu
displayed fields: Configuration
displayed tag fields: View Menu
documentation, installing: Building from Source
duplicate album field: Editing the Metadata
duplicate artist field: Editing the Metadata
duplicate fields: Edit Menu
duplicate filenames: Invoking

E
edit image setup: Edit Menu
edit menu: Edit Menu
edits-pending indicators: Application Layout
execution path: Building from Source

F
f option: Invoking
F option: Invoking
fields, activate all: View Menu
fields, duplicate: Edit Menu
file menu: File Menu
file, shift position: View Menu
file, sort option: View Menu
filename characters: Invoking
free space on target: View Menu

G
genre, list of: Editing the Metadata

H
h option: Invoking
headers, ASF (WMA): Tech Notes
headers, MP3: Tech Notes
headers, OGG/Vorbis: Tech Notes
help menu: Help Menu
help option: Invoking
hotkey list: Navigation

I
i option: Invoking
I option: Invoking
image data, view: View Menu
image vector OGG: Tech Notes
image, add: Edit Menu
image, edit setup: Edit Menu
image, ogg: Tech Notes
image, save extracted: View Menu
info database: Building from Source
install the binary: Building from Source
interface, user: User Interface
interface, user: Dialog Controls
invert, RTL: View Menu

L
l option: Invoking
L option: Invoking
languages, list of: Editing the Metadata
languages, RTL: UI Languages
layout, dialog: Application Layout
list control: Dialog Controls
list of genres: Editing the Metadata
list of languages: Editing the Metadata

M
m option: Invoking
menu bar: Menu Access
menu control: Dialog Controls
menu, edit: Edit Menu
menu, file: File Menu
menu, help: Help Menu
menu, sort-by: Sort-by Submenu
menu, view: View Menu
metadata, ASF: Tech Notes
metadata, MP3: Tech Notes
metadata, OGG/Vorbis: Tech Notes
meter, popularity: Edit Menu
mouse, navigation via: Navigation
MP3 Headers: Tech Notes
MP3 metadata: Tech Notes
MP3 standard: Tech Notes

N
navigation keys: Navigation
navigation via mouse: Navigation

O
ogg image: Tech Notes
OGG/Vorbis Headers: Tech Notes
OGG/Vorbis metadata: Tech Notes
OGG/Vorbis standard: Tech Notes
option, a: Invoking
option, album: Invoking
option, artist: Invoking
option, c: Invoking
option, C: Invoking
option, d: Invoking
option, D: Invoking
option, f: Invoking
option, F: Invoking
option, h: Invoking
option, help: Invoking
option, i: Invoking
option, I: Invoking
option, l: Invoking
option, L: Invoking
option, m: Invoking
option, p: Invoking
option, P: Invoking
option, s: Invoking
option, version: Invoking
options, command-line: Invoking

P
p option: Invoking
P option: Invoking
path, execution: Building from Source
play counter: Edit Menu
popularity meter: Edit Menu
position, shift file: View Menu
pushbutton control: Dialog Controls
pushbutton, save-all: File Menu

R
radiobutton control: Dialog Controls
request, tech support: Help Menu
RTL field invert: View Menu
RTL languages: UI Languages

S
s option: Invoking
save extracted image: View Menu
save-all pushbutton: File Menu
save-files dialog: File Menu
scheme, color: View Menu
screenshot, dialog: Operational Overview
set color scheme: View Menu
shift file position: View Menu
shortcut key list: Navigation
size, dialog: Dialog Dimensions
sort-by menu: Sort-by Submenu
sort-by option: View Menu
source code, Taggit: Building from Source
special characters: Invoking
spinner control: Dialog Controls
standard, ASF (WMA): Tech Notes
standard, MP3: Tech Notes
standard, OGG/Vorbis: Tech Notes
summary, tag data: View Menu
support, technical: Technical Support

T
tag data summary: View Menu
tag fields, active: View Menu
target space available: View Menu
tech support request: Help Menu
technical support: Technical Support
temporary files: Building from Source
test the build: Building from Source
textbox control: Dialog Controls

U
usage: Invoking
user interface: User Interface
user interface: Dialog Controls

V
vector, image OGG: Tech Notes
version option: Invoking
view image data: View Menu
view menu: View Menu

Jump to:   0  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   R   S   T   U   V