ADC Home > Reference Library > Reference > Audio > Carbon > Disc Recording Framework Reference
|
DRCoreCDText.h |
Includes: |
CD-Text object used in the Disc Recording APIs.
CD-Text allows the authors of an audio CD to encode textual
information about the CD and its tracks onto the disc. Information such as
album name, track names, artist, songwriter, performer, and more can be
encoded this way. When a disc containing CD-Text is inserted into a CD-Text
aware player, this information is displayed as the CD plays.
CD-Text is only for audio CDs; it does not apply to and does not work on
data CDs or DVDs.
Here's a conceptual description of how CD-Text works. The CD-Text information for
a disc can contain up to eight blocks of textual information. Each block has an
associated language code and character set, and contains a complete set of
information about the disc.
+----------------------------+ | +------------------------+ | | | CD-Text block 1 | | | | - language code | | | | - character set | | | +------------------------+ | | . | | . | | . | | +------------------------+ | | | CD-Text block 8 | | | | - language code | | | | - character set | | | +------------------------+ | +----------------------------+
+----------------------------+ | CD-Text block | | - language code | | - character set | | +------------------------+ | | | Index 0 - disc info | | | +------------------------+ | | +------------------------+ | | | Index 1 - track 1 info | | | +------------------------+ | | +------------------------+ | | | Index 2 - track 2 info | | | +------------------------+ | | . | | . | | . | | +------------------------+ | | | Index n - track n info | | | +------------------------+ | +----------------------------+
+----------------------------+ | Track info dictionary | | | | Title = "title" | | Artist = "artist" | | Performer = "performer" | | . | | . | | . | +----------------------------+
DRCDTextBlockCreate |
Creates a CD-Text block with the provided contents.
extern DRCDTextBlockRef DRCDTextBlockCreate( CFStringRef language, CFStringEncoding encoding) ;
language
encoding
A new CD-Text block.
DRCDTextBlockCreateArrayFromPackList |
Parses raw CD-Text data into DRCDTextBlock objects.
extern CFArrayRef DRCDTextBlockCreateArrayFromPackList( CFDataRef packs) ;
packs
A CFArray object containing DRCDTextBlock objects describing the information in the raw PACKs, or NULL if the data could not be parsed. The caller is responsible for releasing this array.
You can use this function to parse any data blob containing CD-Text PACKs,
such as the result of DRDeviceReadCDText, or the data returned by the
IOKit ioctl DKIOCCDREADTOC with format=5.
The CFData should be sized to fit the exact number of PACKs. Each PACK
occupies 18 bytes, and the 4-byte header from a READ TOC command may
optionally be included.
DRCDTextBlockFlatten |
Flattens the CD-Text block to determine whether any information will be truncated.
extern UInt32 DRCDTextBlockFlatten( DRCDTextBlockRef block) ;
block
The number of bytes that will be truncated from the CD-Text block. If this function returns 0, no truncation will occur.
When burning your CD-Text information to a CD, Disc Recording will automatically
truncate some of the information you've specified if it does not fit.
The size limit for CD-Text is approximately 3K per block. This limit
is approximate because of overhead and because duplicate strings can sometimes be
combined. The only way to determine the final byte size of a CD-Text block is to
ask Disc Recording to flatten it. You can then determine whether
truncation will be needed.
Disc Recording's truncation preserves the most important information and provides
the simplest user experience. If you do not wish to use Disc Recording's automatic
truncation, it is your responsibility to ensure that you provide CD-Text block
content that fits.
Following is a simple algorithm to avoid having your CD-Text data truncated:
DRCDTextBlockGetProperties |
Returns properties of the CD-Text block.
extern CFDictionaryRef DRCDTextBlockGetProperties( DRCDTextBlockRef block) ;
block
A CFDictionary object containing the properties of the specified CD-Text block. The caller does not implicitly retain the reference, and is not responsible for releasing it.
DRCDTextBlockGetTrackDictionaries |
Returns the array of track dictionaries for a given block.
extern CFArrayRef DRCDTextBlockGetTrackDictionaries( DRCDTextBlockRef block) ;
block
A CFArray object containing immutable dictionaries of CFString objects, each of which contains CD-Text information.
Each item in the array is a dictionary, which in turn holds key-value encoded information about a track or disc. Array index 0 holds information about the disc, index 1 holds information about track 1, index 2 holds information about track 2, and so on. The caller does not implicitly retain the reference, and is not responsible for releasing it.
DRCDTextBlockGetTypeID |
Returns the type identifier for all DRCDTextBlock instances.
extern CFTypeID DRCDTextBlockGetTypeID( void) ;
A Core Foundation type identifier.
DRCDTextBlockGetValue |
Returns one specific value for a track.
extern CFTypeRef DRCDTextBlockGetValue( DRCDTextBlockRef block, CFIndex trackIndex, CFStringRef key) ;
block
trackIndex
key
A Core Foundation type reference reference to a copy of the specified CD-Text block value.
This function looks up the value for the specified track index and key, and returns the value. The returned value will be a CFString, CFData, or CFNumber object, or will be NULL if no key was found. The caller does not implicitly retain the reference, and is not responsible for releasing it.
DRCDTextBlockSetProperties |
Sets the properties of the CD-Text block.
extern void DRCDTextBlockSetProperties( DRCDTextBlockRef block, CFDictionaryRef properties) ;
block
properties
DRCDTextBlockSetTrackDictionaries |
Sets an array of track dictionaries for a given CD-Text block.
extern void DRCDTextBlockSetTrackDictionaries( DRCDTextBlockRef block, CFArrayRef array) ;
block
array
Each item in the array is a dictionary, which in turn holds key-value encoded
information about the track or disc. Array index 0 holds information about the
disc, index 1 holds information about track 1, index 2 holds information about
track 2, and so on.
The incoming strings are automatically modified to conform to the character
set specified in the language block. Calling the DRCDTextCopyTrackArray()
function immediately after DRCDTextSetTrackArray() returns the modified values, which
may not be the same as the ones you passed in but correspond to what
will actually be used.
DRCDTextBlockSetValue |
Sets one specific value for a track.
extern void DRCDTextBlockSetValue( DRCDTextBlockRef block, CFIndex trackIndex, CFStringRef key, CFTypeRef value) ;
block
trackIndex
key
value
The CD-Text value may be a CFString, CFData, or CFNumber object, but should correspond
to the type defined in the description of the key.
If the incoming value is a string, it is automatically modified to conform to
the character set of the language block. Calling the DRCDTextCopyValue() function
immediately after DRCDTextSetValue() returns the modified value, which
may not be the same as the one you passed in but corresponds to
what will actually be used.
Setting a value to NULL removes the key from the specified track dictionary.
kDRCDTextArrangerKey |
extern const CFStringRef kDRCDTextArrangerKey;
A CD-Text block dictionary key whose value, a CFString object, contains the name of the arranger for a track or, if for the disc info block, for the disc as a whole.
kDRCDTextCFStringEncodingKey |
extern const CFStringRef kDRCDTextCFStringEncodingKey;
This is a required property key for a CD-Text block. Its value
is a reference to a CFNumber object containing the CFStringEncoding value for the
text of the block.
This property should remain constant once a block is created. If you change
it after creating a block, the results are undefined.
kDRCDTextCharacterCodeKey |
extern const CFStringRef kDRCDTextCharacterCodeKey;
This is a required property key for a CD-Text block. Its value
is a reference to a CFNumber object containing the Red Book character set value
for the text of the block.
The value is not a CFStringEncoding or an NSStringEncoding data type and should
not be used as such.
This property should remain constant once a block is created. If you change
it after creating a block, the results are undefined.
kDRCDTextClosedKey |
extern const CFStringRef kDRCDTextClosedKey;
A CD-Text block dictionary key whose value, a CFString object, contains
arbitrary disc information. The text format is arbitrary and is up to the content
provider. This information is private and players should not display it to the user
of the disc.
In compliance with the CD-Text specifications, this string is always encoded using
the kDRCDTextEncodingISOLatin1Modified encoding, regardless of the block's encoding.
kDRCDTextComposerKey |
extern const CFStringRef kDRCDTextComposerKey;
A CD-Text block dictionary key whose value, a CFString object, contains the name of the composer for a track or, if for the disc info block, for the disc as a whole.
kDRCDTextCopyrightAssertedForNamesKey |
extern const CFStringRef kDRCDTextCopyrightAssertedForNamesKey;
This is an optional property key for a CD-Text block. Its value
is a reference to a CFBoolean object that indicates whether copyright is asserted on the
names in the block, which include the values associated with the kDRCDTextPerformerKey,
kDRCDTextSongwriterKey, kDRCDTextComposerKey, and kDRCDTextArrangerKey keys.
If this value is not specified, no copyright is asserted for these items.
kDRCDTextCopyrightAssertedForSpecialMessagesKey |
extern const CFStringRef kDRCDTextCopyrightAssertedForSpecialMessagesKey;
This is an optional property key for a CD-Text block. Its value
is a reference to a CFBoolean object that indicates whether copyright is asserted on the
block text associated with the kDRCDTextSpecialMessageKey key.
If this value is not specified, no copyright is asserted for the text.
kDRCDTextCopyrightAssertedForTitlesKey |
extern const CFStringRef kDRCDTextCopyrightAssertedForTitlesKey;
This is an optional property key for a CD-Text block. Its value
is a reference to a CFBoolean object that indicates whether copyright is asserted on the
disc or track title associated with the kDRCDTextTitleKey key.
If this value is not specified, no copyright is asserted for this text.
kDRCDTextDiscIdentKey |
extern const CFStringRef kDRCDTextDiscIdentKey;
A CD-Text block dictionary key whose value, a CFString object, contains disc
identifying information such as the catalog number and name of the record
company, point of sale code, year, and so on. Each item shall be separated by a slash ("/").
In compliance with the CD-Text specifications, this string is always encoded using
the kDRCDTextEncodingISOLatin1Modified encoding, regardless of the block's encoding.
This key is valid only for the disc as a whole, namely for array index 0. It is ignored
when set in the dictionaries for tracks.
kDRCDTextGenreCodeKey |
extern const CFStringRef kDRCDTextGenreCodeKey;
A CD-Text block dictionary key whose value, a CFNumber object, contains
the numeric code of the genre for the disc as a whole as listed in
the CD-Text Genres enumeration.
This key is valid only for the disc as a whole, namely for array index 0. It is ignored
when set in the dictionaries for tracks.
kDRCDTextGenreKey |
extern const CFStringRef kDRCDTextGenreKey;
A CD-Text block dictionary key whose value, a CFString object, contains
the name of the genre for the disc as a whole.
In compliance with the CD-Text specifications, this string is always encoded using
the kDRCDTextEncodingISOLatin1Modified encoding, regardless of the block's encoding.
This key is valid only for the disc as a whole, namely for array index 0. It is ignored
when set in the dictionaries for tracks.
kDRCDTextLanguageKey |
extern const CFStringRef kDRCDTextLanguageKey;
This is a required property key for a CD-Text block. Its value is a
reference to a CFString object containing the ISO 639 language code
describing the language for the text of the block. CD-Text allows the
concept of an unknown language, which is represented here by an empty
string.
You can change a block's language after creating the block.
kDRCDTextMCNISRCKey |
extern const CFStringRef kDRCDTextMCNISRCKey;
A CD-Text block dictionary key whose value, a CFData object, contains either 13 bytes of Media Catalog Number (MCN, for the disc as a whole) or 12 bytes of International Standard Recording Code (ISRC, for tracks). This information can also be specified in the burn and track properties. CD-Text simply provides an alternative, possibly redundant, way to encode this information. If the MCN or ISRC data was specified in the properties for the burn or track, this value should be the same. See the descriptions of kDRMediaCatalogNumberKey and kDRTrackISRCKey for more details on the precise format of the data.
kDRCDTextPerformerKey |
extern const CFStringRef kDRCDTextPerformerKey;
A CD-Text block dictionary key whose value, a CFString object, contains the name of the performer for a track or, if for the disc info block, for the disc as a whole.
kDRCDTextSizeKey |
extern const CFStringRef kDRCDTextSizeKey;
A CD-Text block dictionary key whose value, a CFData object, contains
information about the number of packs and languages associated with each block.
This key is for output use only, when reading CD-Text from a disc.
It is ignored when specified in a burn.
kDRCDTextSongwriterKey |
extern const CFStringRef kDRCDTextSongwriterKey;
A CD-Text block dictionary key whose value, a CFString object, contains the name of the songwriter for a track or, if for the disc info block, for the disc as a whole.
kDRCDTextSpecialMessageKey |
extern const CFStringRef kDRCDTextSpecialMessageKey;
A CD-Text block dictionary key whose value, a CFString object, contains a text message that may be displayed to the user by some players.
kDRCDTextTitleKey |
extern const CFStringRef kDRCDTextTitleKey;
A CD-Text block dictionary key whose value, a CFString object, contains the title for a track or, if for the disc info block, for the disc as a whole.
kDRCDTextTOC2Key |
extern const CFStringRef kDRCDTextTOC2Key;
A CD-Text block dictionary key whose value, a CFData object, contains
additional table-of-contents information.
This key is for output use only, when reading CD-Text from a disc.
It is ignored when specified in a burn.
kDRCDTextTOCKey |
extern const CFStringRef kDRCDTextTOCKey;
A CD-Text block dictionary key whose value, a CFData object, contains
table-of-contents information.
This key is for output use only, when reading CD-Text from a disc.
It is ignored when specified in a burn.
DRCDTextBlockRef |
A reference to DRCDTextBlock instances.
typedef const struct __DRCDTextBlock* DRCDTextBlockRef;
CD-Text Encodings |
Special CFStringEncoding values supported by the CD-Text format.
enum { kDRCDTextEncodingISOLatin1Modified = kCFStringEncodingISOLatin1, /* ISO-Latin-1, as of Mac OS X 10.5 the appropriate CD-Text variant will now be used */ kDRCDTextEncodingASCII = kCFStringEncodingASCII /* 7-bit ASCII */ };
The CD-Text format supports only encodings listed here.
As of Mac OS X 10.5 two new encodings are supported, they are
kTextEncodingDOSJapanese (kTextEncodingShiftJIS)(CD-Text variant)
and kCFStringEncodingUTF8. Note, they do not have a DR defined value
as with the previously supported encodings.
These new encodings are intended to be specified along side existing
encodings, as to aide in the localization process should multi lingual
CD-Text be desired. Support for Shift JIS, while documented in the
Red Book specification, may not be supported on most CD-Text capable
devices. UTF-8 support is not defined in the Red Book specification
and is to be considered a vendor specific enhancement, implementors
worried about compatibility should avoid its use.
CD-Text Genres |
Numeric values for audio content genres.
enum { kDRCDTextGenreCodeUnknown = 0x0001, kDRCDTextGenreCodeAdultContemporary = 0x0002, kDRCDTextGenreCodeAlternativeRock = 0x0003, kDRCDTextGenreCodeChildrens = 0x0004, kDRCDTextGenreCodeClassical = 0x0005, kDRCDTextGenreCodeContemporaryChristian = 0x0006, kDRCDTextGenreCodeCountry = 0x0007, kDRCDTextGenreCodeDance = 0x0008, kDRCDTextGenreCodeEasyListening = 0x0009, kDRCDTextGenreCodeErotic = 0x000A, kDRCDTextGenreCodeFolk = 0x000B, kDRCDTextGenreCodeGospel = 0x000C, kDRCDTextGenreCodeHipHop = 0x000D, kDRCDTextGenreCodeJazz = 0x000E, kDRCDTextGenreCodeLatin = 0x000F, kDRCDTextGenreCodeMusical = 0x0010, kDRCDTextGenreCodeNewAge = 0x0011, kDRCDTextGenreCodeOpera = 0x0012, kDRCDTextGenreCodeOperetta = 0x0013, kDRCDTextGenreCodePop = 0x0014, kDRCDTextGenreCodeRap = 0x0015, kDRCDTextGenreCodeReggae = 0x0016, kDRCDTextGenreCodeRock = 0x0017, kDRCDTextGenreCodeRhythmAndBlues = 0x0018, kDRCDTextGenreCodeSoundEffects = 0x0019, kDRCDTextGenreCodeSoundtrack = 0x001A, kDRCDTextGenreCodeSpokenWord = 0x001B, kDRCDTextGenreCodeWorldMusic = 0x001C };
CD players can use the numeric codes associated with these
genres to automatically assign equalizer settings. If no
genre code is specified, a value of kDRCDTextGenreCodeUnknown
is used.
You can also specify a textual genre description, using the
kDRCDTextGenreKey CD-Text dictionary key, to supplement
the numeric code. In typical implementations, the textual genre
will be visible to the listener regardless of the genre code.
|