Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access Disc Recording Framework Reference

Overview

CD-Text object used in the DiscRecording APIs.

Discussion

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.

Classes

DRCDTextBlock

Defines a CD-Text block, which holds the CD-Text strings for the entire disc in one language.

Categories

DRCDTextBlock(PropertyConvenienceMethods)

Convenience methods for a DRCDTextBlock.

Constants

DRCDTextArrangerKey

DRCDTextCharacterCodeKey

DRCDTextClosedKey

DRCDTextComposerKey

DRCDTextCopyrightAssertedForNamesKey

DRCDTextCopyrightAssertedForSpecialMessagesKey

DRCDTextCopyrightAssertedForTitlesKey

DRCDTextDiscIdentKey

DRCDTextGenreCodeKey

DRCDTextGenreKey

DRCDTextLanguageKey

DRCDTextMCNISRCKey

DRCDTextNSStringEncodingKey

DRCDTextPerformerKey

DRCDTextSizeKey

DRCDTextSongwriterKey

DRCDTextSpecialMessageKey

DRCDTextTitleKey

DRCDTextTOC2Key

DRCDTextTOCKey

extern NSString* const DRCDTextArrangerKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextCharacterCodeKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextClosedKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextComposerKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextCopyrightAssertedForNamesKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextCopyrightAssertedForSpecialMessagesKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextCopyrightAssertedForTitlesKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextDiscIdentKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextGenreCodeKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextGenreKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextLanguageKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextMCNISRCKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextNSStringEncodingKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextPerformerKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextSizeKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextSongwriterKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextSpecialMessageKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextTitleKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextTOC2Key;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.

extern NSString* const DRCDTextTOCKey;  

Discussion

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.

Availability

Introduced in Mac OS X v10.4.