VTFI FORMAT SPECIFICATION

OVERVIEW

The VisiTrax Text File Interchange (VTFI) format is used by VisiTrax to read or write library data as text. VTFI is intended to facilitate

• migrating data from other software into VisiTrax, and
• using other software (perhaps just a text editor) to make bulk changes of some sort to an existing VisiTrax data library.

When migrating data from another program, note that it's also possible to copy tabular data from a common spreadsheet program and paste it directly into the VisiTrax Tracks view. For details on this generally simpler alternative, see the Help topic entitled "Copy and Paste".

General Description

VTFI provides a flexible, relational representation for music library data. Because it is patterned after the Microsoft Windows INI file format, VTFI can be processed using parsing functions commonly available in the Windows API. [Note: Actual use of such functions under Windows 9x may only be suitable for relatively small text files. This limitation does not apply under Windows NT, Windows 2000, or Windows XP.]

VTFI files typically are used to represent complete music libraries and thus can be rather large. To minimize potential file read time, VisiTrax-generated VTFI files contain no forward references (i.e. processing can be performed in a single pass). However, the VTFI specification itself does not preclude the use of forward references.

Format Design Considerations

VTFI was designed to minimize the need for data repetition, while providing a format that is easy to create or modify with an ordinary text editor. The INI file format was chosen because, in addition to meeting these key criteria, it can represent data records in a sparse manner (space is consumed only by those fields for which meaningful data is available), it is easily expandable, and, as noted previously, the basic format is supported by a number of common Windows API functions.

To address possible implementation concerns, VTFI sections should be kept under 32 Kbytes in length. At this point in time, there is only one case where this limitation must be addressed: artist names. Because many tracks can share the same artist name, it makes sense to maintain a separate list of artist names. VTFI provides a method for dividing a large list of artist names into two or more sections, as necessary, each less than 32 Kbytes in size.

Separate lists also make sense for media format types and music categories, but these latter lists tend to be relatively short, and certainly much less than 32 Kbytes in any event.

Track and volume titles tend to be reused so infrequently that there would be little if any benefit in maintaining separate lists for these in VTFI text files.

To further conserve file space, many of the key names defined herein are kept very short (often a single character).

Data Merge Considerations

Because text files can be edited manually, it is not generally prudent to assume that their data will be in strictly sorted order. Thus, when VisiTrax reads a VTFI file, it re-sorts the new data as it merges it with any already-existing data.

No attempt is made to consolidate duplicate volume records during the import process: if you merge in the same set of 100 volumes three times in a row, you'll end up with 300 new volume records.

SYNTAX DESCRIPTION

General Features

Named Sections

A VTFI text file contains a series of named sections (enumerated in later paragraphs). Each section begins with a line containing the section name in square brackets, e.g. "[SECTION1]" would denote the section named "SECTION1". (By convention herein, section labels will be shown in all-uppercase characters. In practice, however, all label names are treated as case-insensitive.)

Section Contents

Each section consists of one or more key name / value pair lines, in the form "k=v", where "k" represents a (case-insensitive) key name, and "v" represents the data to be associated with the key name (literal text or a number) as a so-called value. No spaces or tabs should appear on either side of the "=" sign.

Blank Lines and Comments

Blank lines, and comment lines that begin with a semicolon (";"), may be placed at any point. Normally, sections are separated by a blank line for human readability.

Literals versus References

For those field types that accept either references (numeric references to previously defined list items) or literals (literal text strings), any mix of literals and references is acceptable within the dataset. Purely numeric value data is assumed to be a reference. In those rare cases where the artist name is purely numeric (e.g. "311"), a reference to the name is recommended (e.g. A2=311 ... A=2).

Undefined References

Numeric references are treated as index values for accessing members of an array of defined text strings (such as artist names). Any reference to a non-defined member of such an array (e.g. A2 not defined but A3 is) will return a zero-length string (empty field).

Data Sorting

All data in a VTFI text file can be non-sorted. Sections can appear in any order, and lines within a given section can appear in any order. However, one should be aware that substantial amounts of non-ordered data can have an adverse impact on processing time.

Numeric Contiguity

For [ARTISTS_n] sections, the applied numbers n must be sequenced contiguously starting with 1. For all other intrinsically numbered items (e.g. category and artist name definitions, track and volume sections), gaps are permitted. For example, artists names A1 and A3 could be defined while A2 is not defined; this is valid as long as there is no need to reference A2.

This "forgiving" characteristic is intended to facilitate arbitrary editing of VTFI files.

Required Definition Sections

[COUNTS] Section

A [COUNTS] section, of the form shown below, must be provided to establish the total number of volumes and tracks, and to establish the assigned range for each [ARTISTS_n] section. Capitalization of key words and labels is unimportant.

[COUNTS]
Volumes=<highest-numbered volume section>
Tracks=<highest-numbered track section>
ARTISTS_1=<maximum number of artists in [ARTISTS_1] section>
...
ARTISTS_n=<maximum number of artists in [ARTISTS_n] section>

The assigned ranges for [ARTISTS_n] sections should be small enough to ensure that the corresponding sections do not exceed 32 Kbytes. In practice, 500 artist names per section is generally safe.

[MEDIA] Section

A [MEDIA] section, of the form shown below, must be provided to define all media types and their prefix codes:

[MEDIA]
<unique two-letter prefix 1>=<media type description 1>
...
<unique two-letter prefix n>=<media type description n>

Every media type listed must have a unique two-letter key name, which will be used as the common locator index prefix for that media type. (VisiTrax will automatically assign a unique two-letter prefix for a media type if none was defined for it by the user.)

Optional Definition Sections

[CATEGORIES] Section

An optional [CATEGORIES] section, of the form shown below, may be provided to permit the use of category references in lieu of literal category strings within track record sections:

[CATEGORIES]
C1=<category>
...
Cn=<category>

[ARTISTS_n] Sections

One or more optional [ARTISTS_n] sections, of the form shown below, may be provided to permit the use of artist references in lieu of literal artist names:

[ARTISTS_n]
Aa=<artist name>
...
Ab=<artist name>

...where a and b represent the first and last index values within the assigned range of key name numbers for the [ARTISTS_n] section.

For example, if in the [COUNTS] section, ARTISTS_1=500 and ARTISTS_2=200, section [ARTISTS_1] would contain any artist names labeled A1 through A500, and section [ARTISTS_2] would contain any artist names labeled A501 through A700.

Database Record Sections

Each database record section causes data to be added into the library database. If all of the database record sections were deleted from a VTFI file, leaving only the definition sections, nothing would be added into the resident VisiTrax library.

Volume Record Sections

A separate [Vaaa] volume record section is used to specify the contents of each volume – where Vaaa is any unique section label starting with the character "V" (any repeated volume sections are ignored during data import). The total number of unique volume sections should not exceed the number of volumes specified in the [COUNTS] section.

The defined key names that can be used in a volume record section are as follows:

L	= Locator index (e.g. CD0123, LP1234.5)
D	= Disc ID as 1-8 hex digits (CDDB type)
M	= Media ID as 1-8 hex digits (CDA type)
A	= Artist (n for An or literal text)
T	= Title
N	= Notes
P	= Pathname (i.e. directory path or folder)
C	= Default track Category
Y	= Default track Year

Track Record Sections

A separate [Tn] track record section is used to specify the contents of each track – where n ranges from 1 to the number of tracks specified in the [COUNTS] section. Each track record section must reference an existing volume record section in order to be imported by VisiTrax.

When reading a VTFI file, VisiTrax ignores the number n in [Tn]; thus, when converting data to text for import purposes, all track sections can be tagged as "[T1]" if desired.

The defined key names that can be used in a track record section are as follows:

V	= Volume index (e.g. for V32, V=32)
N	= Number of track (1-999, A1-99, B1-99)
C	= Category (n for Cn or literal text)
A	= Artist (n for An or literal text)
T	= Title
S	= Subtitle
W	= Composer ("Writer")
F	= Filename
P	= Pathname (i.e. directory path or folder)
Y	= Year
L	= Lead-in time
E	= Elapsed playing time
B	= BPM (tempo)
R	= Notes ("Remarks")

VisiTrax will refer to the corresponding volume record section if a track record section's artist, category, or year is omitted.