DRCDText.h Reference

Declared in
DRCDText.h

Overview

CD-Text object used in the DiscRecording APIs.

CD-Text is a system which 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       | |
   | +------------------------+ |
   +----------------------------+
 

Usually each block of CD-Text will be used to contain a different language (English, French, Japanese, Chinese, etc). However, it's possible and permissible to have multiple blocks that each contain the same language.

Each block encodes a complete set of information about the disc and its tracks. This information is stored as an array of key-value dictionaries; one per track, with an additional dictionary for the disc/album itself (represented by array index 0). On a disc with n tracks, there will be n+1 dictionaries.

 
   +----------------------------+
   | 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 | |
   | +------------------------+ |
   +----------------------------+
 

Finally, the dictionaries for the individual tracks contain the textual information to be displayed. This information is strictly limited to the character set specified by the enclosing block, and is likewise assumed to be in the language specified.

 
   +----------------------------+
   | Track info dictionary      |
   |                            |
   |  Title = "title"           |
   |  Artist = "artist"         |
   |  Performer = "performer"   |
   |            .               |
   |            .               |
   |            .               |
   +----------------------------+
 

For best compatibility with CD players, individual textual items in the dictionaries should be 160 bytes or smaller. Since the currently supported character encodings are all single-byte encodings, this means a maximum of 160 characters per entry.

Included Headers

  • <Foundation/Foundation.h>

  • <CoreServices/CoreServices.h>

  • <DiscRecording/DRCoreCDText.h>

  • <AvailabilityMacros.h>

Constants

See the Overview section above for header-level documentation.

Global Constants

extern NSString* const DRCDTextArrangerKey;
extern NSString* const DRCDTextCharacterCodeKey;
extern NSString* const DRCDTextClosedKey;
extern NSString* const DRCDTextComposerKey;
extern NSString* const DRCDTextCopyrightAssertedForNamesKey;
extern NSString* const DRCDTextCopyrightAssertedForSpecialMessagesKey;
extern NSString* const DRCDTextCopyrightAssertedForTitlesKey;
extern NSString* const DRCDTextDiscIdentKey;
extern NSString* const DRCDTextGenreCodeKey;
extern NSString* const DRCDTextGenreKey;
extern NSString* const DRCDTextLanguageKey;
extern NSString* const DRCDTextMCNISRCKey;
extern NSString* const DRCDTextNSStringEncodingKey;
extern NSString* const DRCDTextPerformerKey;
extern NSString* const DRCDTextSizeKey;
extern NSString* const DRCDTextSongwriterKey;
extern NSString* const DRCDTextSpecialMessageKey;
extern NSString* const DRCDTextTitleKey;
extern NSString* const DRCDTextTOC2Key;
extern NSString* const DRCDTextTOCKey;
Constants
DRCDTextArrangerKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing the track/disc arranger.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextCharacterCodeKey

Required property key for a CD-Text block. The value for this property is an NSNumber, containing the Red Book character set value for the text of the block. This value is not a CFStringEncoding or NSStringEncoding, and should not be used as such.

This property should remain constant once the block is created. If this property is changed after the block is created, the results are undefined.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextClosedKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing disc information. The format of this data 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.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextComposerKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing the track/disc composer.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextCopyrightAssertedForNamesKey

Optional property key for a CD-Text block. The value for this property is an NSNumber, containing a BOOL value indicating whether copyright is asserted on the names in the block. (DRCDTextPerformerKey , DRCDTextSongwriterKey , DRCDTextComposerKey , DRCDTextArrangerKey )

If this value is not specified, no copyright is asserted for these items.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextCopyrightAssertedForSpecialMessagesKey

Optional property key for a CD-Text block. The value for this property is an NSNumber, containing a BOOL value indicating whether copyright is asserted on the messages in the block (DRCDTextSpecialMessageKey ).

If this value is not specified, no copyright is asserted for these items.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextCopyrightAssertedForTitlesKey

Optional property key for a CD-Text block. The value for this property is an NSNumber, containing a BOOL value indicating whether copyright is asserted on the titles of the disc and tracks. (DRCDTextTitleKey )

If this value is not specified, no copyright is asserted for these items.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextDiscIdentKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing disc ID information, such as the catalog number and name of the record company, point of sale code, year of sales, etc. Each item shall be separated by a slash ("/").

This key is only valid for the disc (array index 0) and is ignored when set in the dictionaries for tracks.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextGenreCodeKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSNumber, containing the numeric code for the disc genre as enumerated above.

This key is only valid for the disc (array index 0) and is ignored when set in the dictionaries for tracks.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextGenreKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing the description of the disc genre.

This key is only valid for the disc (array index 0) and is ignored when set in the dictionaries for tracks.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextLanguageKey

Required property key for a CD-Text block. The value for this property is an NSNumber, containing the numeric code for the language. This value is the Red Book language code value for the text of the block.

The language may be changed after the block is created.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextMCNISRCKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSData, containing either 13 bytes of MCN (for the disc) or 12 bytes of 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 was specified in the properties for the burn or track, this value should be the same. See the descriptions of DRMediaCatalogNumberKey and DRTrackISRCKey for more details on the precise format of the data.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextNSStringEncodingKey

Required property key for a CD-Text block. The value for this property is an NSNumber, containing the NSStringEncoding for the text of the block.

This property should remain constant once the block is created. If this property is changed after the block is created, the results are undefined.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextPerformerKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing the track/disc performer.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextSizeKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSData, containing information about the number of packs and languages associated with each block.

This key is provided for output purposes only, when reading CD-Text from an existing disc. It is ignored when specified in a burn.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextSongwriterKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing the track/disc songwriter.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextSpecialMessageKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing a text message which may be displayed to the user by some players.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextTitleKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSString, containing the track/disc title.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextTOC2Key

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSData, containing additional table-of-contents information.

This key is provided for output purposes only, when reading CD-Text from an existing disc. It is ignored when specified in a burn.

Available in OS X v10.4 and later.

Declared in DRCDText.h.

DRCDTextTOCKey

One of the keys for the track dictionaries in a CD-Text block. The value for this key is an NSData, containing table-of-contents information.

This key is provided for output purposes only, when reading CD-Text from an existing disc. It is ignored when specified in a burn.

Available in OS X v10.4 and later.

Declared in DRCDText.h.