AFsetInfo

Routine:

void AFsetInfo(const char InfoRec[])

Purpose:

Add an audio file information record

Description:

This routine adds an information string to be written to an audio file header or trailer. By default standard information records (see below) are used. This routine allows the user to specify information records that are used in addition to, or in place of, the standard information records. This routine must be called before the audio file is opened using AFopnWrite. After the file has been opened the information records are reset. In addition, the default condition (use both the standard information records and the user information records) is re-established.

Standard Information:

 date: 1994-01-25 19:19:39 UTC  date and time
 sample_rate: 8012.5            sampling frequency (if non-integer)
 program: CopyAudio             program name (if set by UTsetProg)
 loudspeakers: FL FR FC         loudspeaker locations (if specified)
 bits_per_sample: 12/16         bits/sample (if specified)

Notes:

- AIFF and AIFF-C files have a floating point representation of the sampling

frequency. As a result, the "sample_rate:" information record will not be generated even for non-integer sampling frequencies.

- For most output formats, the "loudspeakers:" record will be generated if the

loudspeaker locations are specified. For WAVE files, the loudspeaker information appears as part of the WAVE-EX format.

- The bits/sample value is stored in AIFF, AIFF-C, and WAVE-EX files. The

"bits_per_sample:" record will not be generated for AIFF, AIFF, WAVE (promoted to WAVE-EX), or WAVE-EX files.

- For WAVE files, the text from a "program:" or a "date:" information record

is stored in the LIST chunk as detailed below.

- For text audio files, additional information records are generated by

default ("channels:", "frames:", "full_scale:").

If the input information record is empty, the standard information will not be used and any previous user supplied information records will be discarded. Subsequent calls to this routine can be used to specify new information records.

User supplied information records should follow the format of a named field terminated by a colon followed by text. Each time AFsetInfo is called, a user supplied information record is appended to the user information.

Notes:

- WAVE files

These files have provision for storing text information in a DISP or LIST chunk. Text from information records with the following named fields is transferred as follows:

 "display_text:"             => DISP chunk
 "archival_location:"        => IARL field of a LIST/INFO chunk
 "artist:"                   => IART field of a LIST/INFO chunk
 "commissioned:              => ICMS field of a LIST/INFO chunk
 "comment:" or "comments:"   => ICMT field of a LIST/INFO chunk
 "copyright:"                => ICOP field of a LIST/INFO chunk
 "creation_date:", "date:", or "recording_date:"
                             => ICRD field of a LIST/INFO chunk
 "engineer:"                 => IENG field of a LIST/INFO chunk
 "genre:"                    => IGNR field of a LIST/INFO chunk
 "keywords:"                 => IKEY field of a LIST/INFO chunk
 "medium"                    => IMED field of a LIST/INFO chunk
 "title:" or "name:"         => INAM field of a LIST/INFO chunk
 "product:"                  => IPRD field of a LIST/INFO chunk
 "subject:"                  => ISBJ field of a LIST/INFO chunk
 "software:" or "program:"   => ISFT field of a LIST/INFO chunk
 "source:"                   => ISRC field of a LIST/INFO chunk
 "source_form:"              => ISRF field of a LIST/INFO chunk
 "technician:"               => ITCH field of a LIST/INFO chunk

When the audio file is opened with AFopnRead, the information records will have the identifier of the first identifier if multiple identifiers are available. For instance a record stored in the INAM field will have an identifier "title:".

- AIFF and AIFF-C files

These files have provision for storing text informant in a NAME, AUTH, (c) , or ANNO chunk. Text from the information with the following named fields is transferred as follows:

  "title:" or "name:"        => NAME chunk
  "artist:" or "author:"     => AUTH chunk
  "copyright:"               => (c)  chunk
  "comment:", "comments:", or "annotation:"
                             => ANNO chunk

- AFsetInfo("")

This form contains an empty record which signals that the standard information records are not created. Subsequent user supplied records will be used.

- AFsetInfo("<record>")

Append a user information record. Note that the information from a record with "title:", "name:", "comment:", "comments", "utterance_id:, or "display_text:" as an identifier is printed along with file information when that file is opened for writing. Subsequently opening the file for reading with AFopnRead will also display this description.

The information records are stored in the header of the output file.

AU files:: The information records appear just before the start of audio data. The identifier tag "AFsp" marks the beginning of the information records.
AIFF and AIFF-C files:: The collection of information records which have not been reallocated to the NAME, AUTH, (c) , or ANNO chunks are placed in a separate ANNO chunk with an "AFsp" identifier as a prefix.
WAVE files:: The information records which have not been reallocated to the DISP or LIST chunks appear in an "afsp" chunk.
Text audio files:: The information records are written to the header.

Parameters:

<- void AFsetInfo
-> const char InfoRec[]: String containing the user supplied information. If this string is null, standard information records will not be used and any previously entered user information records will be discarded.

Author / revision: