Next: Introduction [Contents][Index]
• Introduction | Features and benefits | |
• Operational Overview | General operational description | |
• Invoking | Command-line arguments and options | |
• User Interface | Navigating through the application | |
• Configuration | Editing the configuration file | |
• Building from Source | Compile the application | |
• Tech Notes | Technical explanation of metadata | |
• Technical Support | Make suggestions, report problems. | |
• Copyright Notice | Boring, but useful. | |
• Index |
Next: Operational Overview, Previous: Top, Up: Top [Contents][Index]
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:
Each of these applications has its strengths and weaknesses. The primary weaknesses are:
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 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: Invoking, Previous: Introduction, Up: Top [Contents][Index]
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.
Author’s Note: We apologize that the documentation is available only in English. Software Sam is an engineer and a teacher, not a linguist, so the level of grammar needed to accurately translate this documentation to other languages is beyond his ability. Software Sam is happy to work with other members of the GNU/Linux community to translate the documentation into additional languages.
Nota del autor: Pedimos disculpas por que la documentación sólo esté disponible en inglés. Nuestra capacidad de leer y escribir en otros idiomas limitado. Software Sam está feliz de trabajar con otros miembros de la comunidad GNU / Linux para traducir la documentación a otros idiomas.
作者注:我们深感抱歉,文档仅供参考用英语。
我们用其他语言阅读和写作的能力有限。
很高兴与 GNU / Linux 社区的其他成员合作将文档翻译成其他语言。
Tác giả của Lưu ý: Chúng tôi xin lỗi rằng các tài liệu có sẵn chỉ bằng tiếng Anh. Khả năng đọc và viết bằng các ngôn ngữ khác là hạn chế. Phần mềm Sam là hạnh phúc để làm việc với các thành viên khác của cộng đồng GNU / Linux để dịch các tài liệu sang ngôn ngữ bổ sung.
The Taggit application is structured as a dialog window based on the author’s 'NcDialog API', which is in turn based on the 'ncursesw' C-language library which is included with all major GNU/Linux distributions.
Compiling and configuring the application is straightforward. Some experience in compiling Linux programs is helpful, but not necessary. The only external library required is the 'ncursesw' development library.
Please see Building from Source for details.
The default configuration file is located in the same directory as the Taggit binary (executable) file. This file sets the default parameters to be used for all sessions.
An alternate configuration file may be specified for special needs.
Please refer to the '-C' option under see Invoking
for details.
Taggit is a console application, so the available command-line options provide the primary configuration for each session.
Please refer to Invoking for a complete list of command-line options.
Taggit is designed to be controlled primarily through mouse input. Although full functionality is available through the keyboard alone, we believe that the layout for this application responds more intuitively to the mouse interface for most operations.
The application requires that the terminal window be sized to:
at least 30 rows by 132 columns.
For optimal operation, it is recommended that the terminal window
be sized to:
37 rows by 156 columns or more.
Please see User Interface for details on navigation among the application’s sub-windows and controls.
The screenshots below are of a 30x132 window which has been compressed to fit within the width of this document.
Please see Tech Notes for a description of the Metadata (tag) structure for each supported audio format.
Next: User Interface, Previous: Operational Overview, Up: Top [Contents][Index]
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
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.
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
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
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"
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:
- When source files are specified using the 'd' option, the application will not scan the current working directory (CWD) for additional source files.
- The 'd' option may be used in conjunction with the 'f' option.
- Note that the 'd' and 'F' options are mutually exclusive. If both are specified, only the first will be accepted.
- Duplicate Filenames
Keep in mind that duplication of source file specifications is not allowed. (See duplicate filenames.)
See also:
'f' option and
'F' option
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 filesIf 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) --------- 248121Summary 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.
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.
- its position relative to the current working directory:
Planes.mp3
./Caribou/Stinker.mp3- its absolute path:
/home/sam/Music/Elton_John/Caribou/Pinky.mp3- its path expressed with simple environment-variable substitution:
${PHONE_MUSIC}/Salvation.oga- If the path to the source item contains spaces, then the token must be enclosed in quotation marks:
'./Rock of the Westies/Island Girl'- Symbolic links in the source path will be followed.
Invocation Examples
taggit -f=’Honky Cat.oga,Rocket Man.oga,Mona Lisas and Mad Hatters.oga’
Important Note:
- When source files are specified using the 'f' option, the application will not scan the directory for additional source files.
- The 'f' option may be used in conjunction with either the 'd' or 'F' options.
- 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
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.txtThis 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.mp3Note 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:
- When source files are specified using the 'F' option, the application will not scan the directory for additional source files.
- The 'F' option may be used in conjunction with the 'f' option.
- Note that the 'F' and 'd' options are mutually exclusive. If both are specified, only the first will be accepted.
- Duplicate Filenames
Keep in mind that duplication of source file specifications is not allowed. (See duplicate filenames.)
See also:
'f' option and
'd' option
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
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.
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.
- English
- Español (Spanish)
- Zhōngwén (中文) (Chinese, simplified)
- Tiếng Việt (Vietnamese)
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.
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
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.
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)
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 fileThe 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
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 discThe 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 ArtistNote 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.
This is the short form of the 'help' option, below.
Invocation Examples
taggit -h
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’
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’
Command-line Help. Display a brief summary of command-line usage and options. (overrides everything on command line except '--version')
Invocation Examples
taggit --helpAlso see 'h' option, for short-form help option.
Display the Taggit version number and copyright information. (overrides everything else on command line)
Invocation Examples
taggit --version
Next: Configuration, Previous: Invoking, Up: Top [Contents][Index]
• User Interface Basics | An overview of application features | |
• Menus | Using menu items to initiate actions | |
• Editing the Filename | The file name edit sub-dialog | |
• Editing the Metadata | The metadata (tag data) edit sub-dialog | |
• UI Languages | Adding user interface languages |
Next: Menus, Up: User Interface [Contents][Index]
• Application Layout | Description of application features | |
• Dialog Dimensions | Size of the dialog in the terminal window | |
• Navigation | Using the mouse, keyboard and shortcut keys | |
• Dialog Controls | Notes on using interface controls effectively |
Next: Dialog Dimensions, Up: User Interface Basics [Contents][Index]
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.
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.
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.
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.)
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.)
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.
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.
Next: Navigation, Previous: Application Layout, Up: User Interface Basics [Contents][Index]
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: Dialog Controls, Previous: Dialog Dimensions, Up: User Interface Basics [Contents][Index]
Navigating through the dialog windows, menus and other application controls is done through the keyboard, the mouse or a combination of the two.
Previous: Navigation, Up: User Interface Basics [Contents][Index]
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.
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 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.
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.
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.
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.
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.
Please see Editing the Metadata for an example of Pushbutton 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.
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.
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.
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: Editing the Filename, Previous: User Interface Basics, Up: User Interface [Contents][Index]
• Menu Access | How to access the Menu Bar | |
• File Menu | Read and write files under edit | |
• Edit Menu | Edit tag data and target filenames | |
• View Menu | Customize the application’s data display | |
• Help Menu | Get application help | |
• Sort-by Submenu | Select the field on which to sort |
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.
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.
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:
The menu will be closed when:
The following chapters provide details about each menu item.
See File Menu.
See Edit Menu.
See View Menu.
See Help Menu.
Next: Edit Menu, Previous: Menu Access, Up: Menus [Contents][Index]
Write all modified data to the target file(s).
Open the 'Save Files' dialog to set the parameters for saving the edited files.
If unsaved modifications have been made to a file, the Filename and/or the Metadata change indicator will be set. To locate the edits-pending indicators, please see Application Layout.
The 'Save Files' dialog may also be invoked using the 'Save All' pushbutton.
See Save Files Dialog, below.
Write the modified data for the highlighted file to the target file.
Open the 'Save Files' dialog to set the parameters for saving the edited file.
See Save Files Dialog, below.
Write the modified data for the highlighted file, but first, specify a different target filename.
This option invokes the rename dialog (see Editing the Filename) so a new filename may be specified, and then switches to the 'Save Files' dialog as in the previous menu items.
See Save Files Dialog, below.
Write the audio data only to the target file. Text and image data (if any) in the source file will be ignored.
See Save Files Dialog, below.
Save a copy of the text metadata fields to a plain-text file.
The following dialog will be opened for selection of save options.
╔═══════════╣ 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:
- Summarize all source files.
Save a metadata summary for each source files.- Summarize only the highlighted file.
Save a metadata summary for the highlighted file only.- Write only fields which contain data.
All text fields which contain data will be written to the summary file. Fields which contain no data will be ignored.- Write all active fields.
Write all active (visible and editable) fields to the summary file, regardless of whether they contain data.- “Save” pushbutton
Save the summary data to the target file and close the dialog.
An information dialog will display the name of the summary file.- ‘Cancel” pushbutton
Close the dialog without saving the summary data.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.
Launch the default media player to play the audio file. If the media player supports display of audio metadata, then the playback also provides an opportunity to view the modified tag data through the external application.
The media player is invoked through the 'xdg-open' system utility. 'xdg-open' is a script file available on most GNU/Linux systems which scans the user’s configuration and extracts the name of the default player. The player is then invoked along with the name of the audio file. For more information, at the command line, type: info xdg-open
Please note that if the audio file’s tag data have been edited, then the edits should be saved before playback; otherwise, the original unmodified audio file will be played.
Re-read the source files and display the metadata they contain. Any previously modified tag data will be discarded.
If you have made a mistake or you are not sure about the edits you have made, use this command to return the data for the displayed files to a known state.
A sub-dialog will be opened to ask for verification before discarding the pending edits.
┌─────────────┤ 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.
Shell out i.e. access the comand line in the current terminal window.
This means that the application will temporarily be put into hibernation mode, and you will be returned to the command prompt.
In hibernation mode, the application is still present in RAM memory, but it is invisible and will not accept input nor produce any output.
Type 'exit' to return to the application.
Exit the application.
Before exiting the application, if changes have been made to the data but have not yet been written to the target file(s), you will be asked whether you want to save or discard the pending edits.
╔════════════════════╣ 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.
Save all active and inactive fields which contain data.
This is the default value and prevents unintended loss of data which is present in the source file but not displayed.
All empty fields (active and inactive) will be ignored
Save all active fields which contain data. Active, but empty fields will be ignored.
All inactive fields will be ignored, regardless of whether they contain data.
Save all active fields which contain data, AND create an empty record for each active (but empty) field.
All inactive fields will be ignored, regardless of whether they contain data.
Technical Note: This option affects primarily MP3 files.
Empty tag records are not allowed under the OGG/Vorbis audio specification.
This option is used to discard all text and image metadata (if any) in the source file, and to save only the audio data to the target file.
Important Note: The name of this option is somewhat misleading: When discarding any existing metadata and writing the audio data only, we actually prepend a placeholder tag header and a small amount of free space to fascilitate addition of metadata at a later time.
This option may be used if the existing metadata are corrupted or in an unknown language, if there is a significant amount of unnecessary padding, or if the metadata are simply unneeded.
Note that any previous changes made to the metadata fields will be discarded. Modifications to the target filename will be saved as specified.
This option may be used to keep an unmodified copy of the source file(s), while the modified data are written to a separate target file.
This option may be selected directly, and may also be preset using the “Preserve” command-line option (see 'P' option).
The source file is renamed as a backup file. Under GNU/Linux, a backup file is one which ends with the 'tilde' ('~') character. For example, if the original source file is named 'Bad Romance.oga', then the backup filename will be 'Bad Romance.oga~'.
The target filename would then be 'Bad Romance.oga' or an alternate filename previously specified (see Editing the Filename).
Before saving the edited data to the target files, a final scan is made of the source files to verify that they are still accessible. This is done to prevent embarrassing access errors during the write cycle. While this test is not foolproof, it does add an extra level of safety for the update process.
If one or more of the source files has become inaccessible, then the following dialog will be invoked to ask permission before proceeding with the update.
┌────────────────┤ 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 │ └──────────────────────────────────────────────────────────┘
Open a sub-dialog for modifying the name of the source file.
The filename may be entered manually, or according to a pattern.
Please see Editing the Filename for more information.
Open a sub-dialog for modifying the data in the tag fields.
Please see Editing the Metadata for more information.
Open a sub-dialog to add an image file to the tag data. This is generally cover art, an image from a concent, a poster or some similar image. A text description of the image may also be added.
Image files may be in either the “Portable Network Graphics” (PNG) format or the “Joint Photographic Experts Group” (JPG) format. While there is no strict limit on image size, it is recommended that image files be approximately ten(10) KBytes or less, while icons should be about 32x32 pixels in size.
Technical Notes: For MP3 files, (id3v2 standard), the parameters
for embedded images are the MIME-type, the “picture category”,
the image size and an optional text description.
(See MP3 Embedded Image.)
Embedded images for the OGG/Vorbis standard are encoded using the FLAC format
which is similar, but not identical to the MP3 format.
(See OGG Images.)
All necessary setup information is collected by this dialog.
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. Examples:
-->file:///home/sam/Pictures/MusicPics/Coldplay/Parachutes01.png
-->file://./Parachutes01.png
This URL would reference an image located outsize the audio file.
However, Taggit does not suport external image references at this time.
╔══════════════════════╣ 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.
- Textbox for entering the source image filename.
Enter a valid relative or absolute path for the source image file.Please see 'I' option for information about specifying the image location as a command-line option.
- MIME-type display text.
The MIME-type is set automatically based on the filename extension of the source image file.
Example: ‘Foghat_Live.jpg’ yields “image/jpeg”
Example: ‘Foghat_Live_II.png’ yields “image/png”
Note that if the image is neither PNG nor JPG/JPEG, or if the file is not found, then the MIME-type will be “image/”, and an error message will be displayed.- Image Size
This is the size of the source image in bytes.- Picture Category dropdown control
The id3v2 standard defines twenty-one(21) categories for embedded images. To view the full list, tab to the Dropdown control and press ENTER. Scroll the highlight to the desired picture type and press ENTER again. The selected type will be displayed. (Note that the index of the picture-type, not its text description, is embedded with the image data.)While several images may be embedded into an audio file, only one icon image is allowed, “32x32 file icon” or “Other Icon”.
- Textbox for entering the Image Description
An optional image description may be embedded with the image. This allows the audio player to display this text in addition to (or instead of) the image itself.While several images may be embedded into an audio file, each must have a unique description.
Note that the id3v2 standard specifies that “The description has a maximum length of 64 characters, but may be empty.” This restriction implicitly assumes that one character equals one data byte which is frankly ridiculous. Taggit interprets this restriction literally, and allows descriptions of up to 64 characters regardless of how many bytes of storage the string requires.
The OGG/Vorbis standard does not impose this restriction.- Save-To-Current-File pushbutton
Save the specified image data into the highlighted file only.- Save-To-All-Files pushbutton
Save the specified image data into all files in the list.- Cancel pushbutton
Discard the image setup and return to the main application.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.
While the ‘Add Image File’ command above provides setup and insertion of a new image file, ‘Edit Image Stats’ enables editing of the setup data for an image that is already associated with the audio file. This includes images which are embedded in the source audio file and images which have been added using the ‘Add Image File’ command.
╔═════════════════════╣ 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.
- Name of image file.
This could be a temporary file containing an image extracted from the source audio file or could be an external image file added earlier (see previous menu item).- MIME-type display text.
The MIME-type of the image: “image/jpeg”, “image/png” or “image/”.Note that the specification allows for a URL in this field referencing an external image; however, Taggit does not support external image references at this time.
- Image Size
This is the size of the source image in bytes.- Picture Category dropdown control
The id3v2 standard defines twenty-one(21) categories for embedded images. To view the full list, tab to the Dropdown control and press ENTER. Scroll the highlight to the desired picture type and press ENTER again. The selected type will be displayed. (Note that the index of the picture-type, not its text description, is embedded with the image data.)- Textbox for entering the Image Description
An optional image description may be embedded with the image. This allows the audio player to display this text in addition to (or instead of) the image itself.Note that the id3v2 standard specifies that “The description has a maximum length of 64 characters, but may be empty.” The OGG/Vorbis standard does not impose this restriction.
- Save pushbutton
Save the edits and return to the main application dialog.
The edited data will be attached to the embedded image when the target file is written. The modified data will be written to the target file when one of the 'Save' options in the File Menu is selected.- Next-image pushbutton
Display the data for the next image in the list.If there is only one image (or no image) associated with the audio file, this pushbutton will be disabled.
- Delete-This-Image pushbutton
Remove the current image and the associated setup information from the audio file. An image marked for deletion will remain visible until the dialog window is closed, but its filename field will be grayed out.When the dialog’s ‘Save’ pushbutton is selected, image data selected for deletion will be removed from the file’s work buffer, and the data will not be included in the tag data written to the target file.
To retrieve the discarded image, see Refresh Displayed Data.
- Cancel pushbutton
Discard the edits and return to the main application.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.
For the highlighted file, discard all edits and re-read the tag data from the source file.
Automatically initialize the 'Track' field for all files.
Track numbers will be assigned sequentially in the order the files are displayed. Any existing data in the 'Track' fields will be overwritten.
Open a sub-dialog for duplicating the contents of a tag field to all files.
Select a field from from the list and duplicate its contents to the corresponding field in each file.
Any active field may be duplicated; however, for some fields, such as the 'Title' field, it makes no sense to set the text for all files to the same value.
╔═══════════════════════════════╣ 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.) ║ ║ └────────────────────────────────┘ ║ ╚════════════════════════════════════════════════════════════════════════════════════════╝
For all files, set the 'Title' field based on the filename (but without the filename extension).
Example: If the filename is 'My Heart Will Go On.oga', then for that file, the 'Title' field would become 'My Heart Will Go On'.
A dialog will be opened asking you to verify the operation.
┌─────────────────┤ 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 │ └───────────────────────────────────────────────────────┘
The id3v2 (MP3) standard defines a “Popularimeter” tag field which media players interpret as a “star rating”. This rating provides a way to compare the relative popularity of different songs or other audio recordings.
The standard also defines a “Playback Counter” which media players can increment each time the audio file is played. While this counter is useful primarily for commercial broadcasters, it also has some value to the music enthusiast.
While these are not text tags, and therefore not of primary interest in this application, they are often available to users from within media-player software. For this reason Taggit provides direct access to these tags through the ‘Popularity and Play Counter’ dialog.
╔══════════════════╣ 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:
- Set Popularity Meter
This is a Spinner control which allows for manually setting the popularity meter to any value between 0 and 255.
Media players interpret this value as a “star rating”, but unfortunately they do so in unstandardized ways. The range of values which represents each step of the star rating is a point of contention among vendors. Please consult the documentation for your media player to determine how the star rating is interpreted.
Taggit displays a nominal star rating just above the popularity-meter control. This rating is determined by mathematical formula rather than by some arbitrary (emotion-producing) marketing scheme concocted by Microsoft(tm), Apple(tm) Google(tm) or some other media-player giant. And unlike these industry players, we are happy to publish our calculations:
A zero value indicates 'no stars' or 'rating unknown'. 1 through 255 == 255 integer values From 1/2 star to 5 stars by half-star increments == 10 steps. 255 / 10 == 25.5 integer values per step. These values are distributed evenly with 1/2 stars having a range of 25 values, and whole stars having a range of 26 values. (25 * 5) + (26 * 5) == 125 + 130 == 255 (How hard is that, Microsloth?!) Star Rating Popularimeter Range ------------------- ------------------- " " 0.0 stars 0 "½ " 0.5 stars 1 - 25 "☺ " 1.0 stars 26 - 51 "☺½ " 1.5 stars 52 - 76 "☺☺ " 2.0 stars 77 - 102 "☺☺½ " 2.5 stars 103 - 127 "☺☺☺ " 3.0 stars 128 - 153 "☺☺☺½ " 3.5 stars 154 - 178 "☺☺☺☺ " 4.0 stars 179 - 204 "☺☺☺☺½" 4.5 stars 205 - 229 "☺☺☺☺☺" 5.0 stars 230 - 255Again, this is merely a nominal reference and disagrees substantially with Window Media Player(tm), MediaMonkey(tm) and with every other media player we have examined.
Please see Spinner Controls for notes on using Spinners effectively.
- Popularity Message
This field is defined by the id3v2 standard for an email address to which the star rating can be sent. However, in practice this field is typically used to hold the name of the media player which most recently updated the star rating, or it is left blank.
Example: Taggit 0.0.03 The Software SamuraiPlease be aware that the id3v2 standard also defines a seldom used “personal play counter” which is associated with the Popularimeter. Taggit always sets this counter to zero when the Popularimeter is initialized. (See the public play counter below.)
- Set Play Counter
This is a Spinner control which allows for manually setting the playback counter to any value between 0 and 99,999. Media players can increment this counter each time the audio is played.
This counter is stored in the audio file as an unsigned 32-bit integer. This means that up to 4,294,967,296 plays may be recorded. However, the standard goes further, stating that when this 32-bit value reaches terminal count, an additional 8 bits may be prepended and the count may continue.
First, kudos to the standards committee for planning ahead — way ahead. If you play a song four billion times, you definitely deserve to keep the count going. However, returning to the real world, Taggit encodes 32 bits only. If the play counter in your audio file actually does reach terminal count, please email it to us and Software Sam will happily widen the counter by eight additional bits.
- SAVE Pushbutton
Encode the Popularimeter and Play Counter data. These data will not be written immediately, but will be included in the tag data written to the target.
- CANCEL Pushbutton
Discard any changes and return to the main application.
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.
For the highlighted file, erase (discard) all data in all metadata fields. All metadata fields for the file will be blank. Embedded image data will also be discarded.
This operation does not immediately modify the target file. Select one of the 'Save' options in the File Menu to update the target file.
For ALL files, erase (discard) all data in all metadata fields. All metadata fields for all files will be blank. Embedded image data will also be discarded.
This operation does not immediately modify the target file(s). Select one of the 'Save' options in the File Menu to update the target files.
This item has not yet been implemented, and cannot be selected.
To set application preferences, edit the configuration file.
Please see Configuration for more information.
Activate all text-tag fields for display and edit.
By default, the selection of active (editable) tag fields is taken from the configuration file. Please see included tag fields section under Configuration for instructions on configuring the application to display specific metadata fields. Generally, only the most useful fields are activated, while seldom-used or special-purpose fields are left inactive and invisible.
Occasionally however, it is advantageous to activate all tag fields to see what, if anything, others (encoders, DJs, streaming media outlets, advertizers) may have written into those fields.
Please see 'a' option command-line option which overrides the configuration and activates all tag fields on startup.
Note that image tags (embedded images) are always accessible and are not affected by this command.
View a summary of the metadata for all source files.
For each source file, all fields that contain data will be displayed in a simple list format as shown below. Note that a brief description of each embedded image and the “Popularimeter” will also be displayed.
# Metadata Summary - 2017-03-20T07:56:35 (Taggit) ------------------------------------------------------------ # Low Rider.mp3 Title ------------------------ Low Rider Artist ----------------------- War Album ------------------------ Dazed and Confused Track ------------------------ 10 Year ------------------------- 1994 Genre ------------------------ (17) Guest Artist or Group -------- Soundtrack Record Label, Publisher ------ Giant Composer(s) ------------------ Charles Miller/Harold Brown Playback Time (mSec) --------- 193306 Image: 9,755 bytes, Type:Cover (front), Desc:D&C Soundtrack, vinyl. Popularity: 175 of 255, (0) Message:'Taggit 0.0.02' Play-count: 12
To save the metadata summary to a file, see Save Tag Summary in the ‘File’ menu.
Another way to get a quick summary of the metadata is to invoke the application using the 'Dump' 'D' option.
The displayed audio files may be sorted alphabetically, low-to-high, on any of the following display fields:
The sort criterion is selected through the Sort-By submenu.
Please see Sort-by Submenu for details.
In addition to arranging the displayed files according to the selected sort criterion (above), the position of any file in the list may be shifted upward or downward.
To shift a file’s position in the display, highlight the file using the arrow keys or the mouse scroll wheel. Then open the 'View' menu and select the 'Shift File Down' or 'Shift File Up' menu item.
The filename and tag information will be shifted in the indicated direction.
The same operation can be performed on the highlighted file using the hotkeys associated with the menu items:
Shift File Down : ALT+DownArrow
Shift File Up : ALT+UpArrow
Report statistics on the target filesystem.
When expanding and writing large files such as music files, it is possible to run low on storage space. Use this option to report the number of logical blocks, number of bytes used and number of free bytes on the target disc or other storage device.
┌─────────────┤ 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 │ └───────────────────────────────────────────────────────┘
An audio file may contain one or more embedded images which can be displayed by media players during playback. The image(s) may be accompanied by a short text description which can be displayed in addition to or instead of the image itself.
Because Taggit is a console application, the image(s) cannot be displayed directly; however, the text description and other encoding information will be displayed with an option to invoke an external application to view the image files.
╔══════════════════╣ 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:
- open Nautilus (or other file manager)
- find a file with an extension of ’jpg’
- right-click the file and select "properties"
- click the "open-with" tab
- select the desired application
- click the "set-as-default" button
- 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.
When the application is invoked with an RTL (right-to-left) user interface language, then this menu item is available to reverse the order of characters in Textbox controls.
Because tag data may be written in a language different from the user interface language of the Taggit application, most tag data fields may be displayed and edited either as LTR data or as RTL data.
The exceptions are purely numeric fields, date/time fields and preformatted fields. Fields which contain mixed LTR/RTL data may be edited in whichever mode is most convenient.
Note also that most sub-dialogs which contain editable data have a Pushbutton control to switch the field between LTR and RTL display.
Please see RTL language support for additional information on RTL user-interface languages.
This menu option is disabled for LTR (left-to-right) user interface languages.
Select the “Color Scheme” for the application.
The color-scheme dialog displays a list of available colors on the left. As you scroll through the list, an example layout for the highlighted color scheme is displayed on the right. Highlight the desired color, and then press the 'SAVE' pushbutton.
╔══════════════════════╣ 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: Sort-by Submenu, Previous: View Menu, Up: Menus [Contents][Index]
Invoke the 'info' document reader to display the application’s documentation.
The Taggit application is temporarily put into hibernation mode so that the 'info' reader can be run in the same terminal window.
The documentation file, 'taggit.info' (or a symbolic link to it) should be located in the same directory as the 'taggit' binary. If the 'taggit.info' document is not found, then the call to the info reader will fail.
Taggit documentation may also be directly invoked from outside the
application.
Assuming that 'taggit.info' in located in: ~/bin
info -f ~/bin/taggit.info
Please see Installation for more information.
Invoke the default web browser to display the HTML version of the application’s documentation.
The documentation file, 'taggit.html' and the 'infodoc-styles.css' style definitions should be located in the same directory as the 'taggit' binary. Alternatively, a symbolic link to the HTML file may be used. If the 'taggit.html' document is not found, then the invocation will fail. If the CSS style definition file is not found, then the HTML file will open, but the formatting will be incorrect.
Please see Installation for more information.
Display a dialog containing a quick reference on application navigation.
This is a simplified version of the Navigation chapter of this document.
Select this menu item to open a standard ‘Help About’ dialog containing application version, copyright information and information needed when making a request for technical support.
╔═══════════════════════╣ 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.
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:
This menu displays the list of fields on which the display data may be sorted.
All options sort in ascending order (low-to-high).
Sort according to the filename. (default)
Sort according to the song title.
Sort according to the album name.
Sort according to the track number.
Sort according to the performer’s name.
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: Editing the Metadata, Previous: Menus, Up: User Interface [Contents][Index]
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.
This leading track number in the filename allows the files of an album to be loaded into the media player alphabetically so they can be played in the artist’s intended order. (See example below.)
'01 American Idiot - Greenday.oga'
'02 Jesus of Suburbia - Greenday.oga'
'03 Holiday - Greenday.oga'
'04 Boulevard of Broken Dreams - Greenday.oga'
'05 Are We the Waiting - Greenday.oga'
'06 St. Jimmy - Greenday.oga'
'07 Give Me Novacaine - Greenday.oga'
'08 She's a Rebel - Greenday.oga'
'09 Extraordinary Girl - Greenday.oga'
'10 Letterbomb - Greenday.oga'
'11 Wake Me Up When September Ends - Greenday.oga'
'12 Homecoming - Greenday.oga'
'13 Whatsername - Greenday.oga'
If no pattern option was used to set the name of the current file, then setting the 'Duplicate' option will have no effect.
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: UI Languages, Previous: Editing the Filename, Up: User Interface [Contents][Index]
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.
The features and controls of this dialog are:
This Textbox allows free-form edit for the contents of the field. This control accepts up to 4096 bytes of text data; however, as a general rule text tags should be limited to approximately 200 bytes.
Note that line breaks and other control characters are not allowed.
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.
Please see RTL language support for additional information on
RTL user-interface languages.
Below the Text Edit control is a brief description of the field and the type of information it holds. Example data and/or expected formatting may also be included as part of this description.
This indicator is just to the right of the Text Edit control and indicates
whether the data in the field have been modified.
● (modified)
The application’s color scheme determines the color used to indicate modified data, but for most color schemes modified data is indicated by a red dot.
See Application Layout, for additional information on change indicators.
◀━╸ prev next ╺━▶
These Pushbuttons move the ‘Edit Metadata Fields’ dialog to the previous metadata field (Previous-field) or the next metadata field (Next-field) in the list.
The ‘Previous field’ Pushbutton is also accessible through the CTRL+P hotkey.
The ‘Next field’ Pushbutton is also accessible through the CTRL+N hotkey.
∆ up ∆ ∇ down ∇
Close the ‘Edit Metadata Fields’ dialog and write all tag-field changes for the file under edit to the temporary buffer for that file.
This is the same as the “DONE” Pushbutton, described below except that selecting this control also moves to the next file (Record Down) or previous file (Record Up) in the list and opens the corresponding metadata field of that file for editing.
The ‘Record Down’ Pushbutton is also accessible through the CTRL+D hotkey.
The ‘Record Up’ Pushbutton is also accessible through the CTRL+U hotkey.
These controls are useful when sequentially editing the corresponding field for each of the audio files.
Close the ‘Edit Metadata Fields’ dialog and write all changes made to tag fields to the temporary buffer for the file under edit.
Note that these changes are not written to the target file at this time. To save the changes to the target file, select the 'Save File' item from the 'File' menu, or save using the 'CTRL+S' hotkey.
Please see File Menu for more information.
Close the ‘Edit Metadata Fields’ dialog and discard all changes made to tag fields since the dialog was opened.
Note that any changes made during a previous access to this dialog will remain pending.
Discard the changes made to the current field and restore the previous contents of the field. Data in other tag fields are not modified by this operation.
The following fields have an additional Pushbutton control for selecting values from a list or for other special processing.
Create Title From Filename
This option uses the name of the file under edit to create the title field.
The title will be the filename without the filename extension. For example, a filename of 'Bad Romance.mp3' yields a title of 'Bad Romance'.
Duplicate For All Files
Because all audio files in a group of files under edit is likely to be from the same artist, this option copies the contents of the field under edit to the corresponding field of all files.
Please see Duplicate Fields for more information on duplicating fields across multiple files.
Duplicate For All Files
Because all audio files in a group of files under edit is likely to be from the same album, this option copies the contents of the field under edit to the corresponding field of all files.
Please see Duplicate Fields for more information on duplicating fields across multiple files.
List of Genres
A “genre” is a way to classify a particular musical style. Genres tend to come and go with the fashion of the day. The people in the music business, (generally music critics) like to perform these classifications as a way of comparing and contrasting the styles of various artists.
The recording industry in general and the MPEG audio group in particular have defined certain genres that will be recognized by internet radio, digital media players and other streaming sources which can be displayed during playback.
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.
ISO-639-2 List of Languages
The primary spoken language of the audio may be encoded using one of the three-character language codes specified by the International Organization for Standards ISO-639-2 standard.
This should not be confused with the two-character ISO-639-1 standard which is used by the Taggit application for selection of the User Interface language.
Many audio files are sung/spoken in multiple languages; however, the MPEG standard specifies that this field should reference the primary language used.
The full language list contains well over 100 language codes, which we make no attempt to reproduce. This partial list covers (in descending order) the top 50-60 spoken languages according to the number of native speakers.
It is not our intention to insult or dismiss speakers of other languages.
The author simply does not have the educational background to understand
the distinctions among all the world’s languages and language groups,
and for this we apologize.
For the complete ISO-639-2 list, please visit the U.S. Library of Congress
website at:
<http://www.loc.gov/standards/iso639-2/php/code_list.php>
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: Editing the Metadata, Up: User Interface [Contents][Index]
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.
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.
The following would reference the text for the “Save” pushbutton control:
Labels[language][saveButton]
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.
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.
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.
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: Building from Source, Previous: User Interface, Up: Top [Contents][Index]
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:
- 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.
- 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.
- 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 backgroundPlease 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.
- 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.
- 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.
- 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.
- 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
- 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.)
- 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 = falseIf 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: Tech Notes, Previous: Configuration, Up: Top [Contents][Index]
The Taggit application is written in C++ and is built with the GNU C++ compiler and linker.
Additional libraries and tools:
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.
Instructions for building the library are included with the NcDialog API package.
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:
No optional builds are currently defined.
To test the build, invoke with a request for the Taggit version number. You should get something similar to the following:
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:
For more information on temporary files, please see the documentation for the 'tmpnam_r' C-language function or the coreutils 'mktemp' utility.
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.
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
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).
If you want to remove the menu entry, use the command:
Next: Technical Support, Previous: Building from Source, Up: Top [Contents][Index]
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
The current release of this application supports three(3) audio formats:
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.
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 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
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
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
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.
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
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
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)
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.)
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.
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.
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
Taggit does not modify the Identification Header in any way.
‘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
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
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.
A Comment Vector consists of two parts and takes the form:
cc cc cc cc [uu uu ....]
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
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.
The Comment Vector array is terminated by a “Framing Bit” which is actually an 8-bit value with only the LSB set: 01h.
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.
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.
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.)
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.
The MIME (Multipurpose Internet Mail Extensions) specification
defines the two image types used for MP3 audio files:
image/png lossless compression format
image/jpeg lossy compression format
image/ (default value if format is unknown)
The specification states that this is a null-terminated string of up to 64 “characters”; however, this make no sense at all in the post-ASCII age. We interpret this literally and allow for 64 displayed characters regardless of the number of bytes or columns required to encode/display them.
This description is optional and is often omitted, although we believe this omission to be a logical error similar to omitting the text that accompanies an image reference in an HTML document.
Please see view image data for more information.
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.
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)
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:
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.
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.
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.
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.
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)
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.
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.
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.
Among the user-defined tag fields, the type of data contained in the field may be text, numeric or binary data.
Next: Copyright Notice, Previous: Tech Notes, Up: Top [Contents][Index]
Console applications have always been the most efficient and easily-implemented of computer programs. What they lacked was a friendly and visually-pleasing user interface.
With the NcDialog API, console applications can now be used and understood by experts and novice users alike.
FileMangler performs all basic file management tasks, as well as performing scheduled and ad-hoc file backup and synchronization activities.
FileMangler runs in a console window, and thus provides access to many system tools not available to a GUI application. FileMangler also provides full support for accessing the local Trashcan.
FileMangler is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.
The HTML version of this document was formatted using ‘idpp’ and is displayed using the ‘infodoc-styles.css‘ definition file. Many more examples are available on the author’s website.
The gString class is lightweight, consisting of one C++ source
module and one header file. The gString class may be directly
integrated into an application, or may be built as a link library.
The gString class is also embedded within the NcDialog API library
(see above).
‘srcprof’ can be used to profile source code for high-level languages such as C, C++ and Java, as well as various assembly languages and scripting languages such as Python, Perl and Ruby. For a complete list of currently-supported source languages, please see the Source Profiler documentation.
’srcprof’ can be used both as a productivity-measurement tool and as a tool for testing source code quality based on an evaluation of its ‘maintainability’.
Source Profiler is a console-based utility, which runs as either a pure, command-line utility, OR as a dialog application based on the NcDialog API.
‘dvdrep’ can be used to rescue data from any non-encrypted DVD video source disc that is formatted using the Universal Disc Format (UDF) filesystem (as all commercially produced DVD movies are).
‘dvdrep’ takes a layered approach to the analysis of the source disc. A detailed log file is maintained for each step of the process in case manual intervention is needed at a later step.
DVD Repair is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.
WaylandCB is a simple C++ class definition which provides console applications with seemless access to the system clipboard.
Next: Index, Previous: Technical Support, Up: Top [Contents][Index]
• GNU General Public License | ||
• GNU Free Documentation License |
Next: GNU Free Documentation License, Up: Copyright Notice [Contents][Index]
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.
“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.
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.
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.
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.
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.
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:
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.
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:
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.
“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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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: GNU General Public License, Up: Copyright Notice [Contents][Index]
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.
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.
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.
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.
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:
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.
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.”
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.
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.
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.
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.
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.
“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.
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:
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
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: Copyright Notice, Up: Top [Contents][Index]
Jump to: | 0
A B C D E F G H I L M N O P R S T U V |
---|
Jump to: | 0
A B C D E F G H I L M N O P R S T U V |
---|