Copyright	(c) 2018-2021 Sam May
License	GPL-3.0-or-later
Maintainer	ag@eitilt.life
Stability	stable
Portability	non-portable (requires libcdio)
Safe Haskell	None
Language	Haskell2010

Foreign.Libcdio.CdText

Contents

Types
Description
Management
Access

Description

Metadata is stored in a binary format both library-internally and on the disc. Most audio archivists will recognize it as "those information fields in a CUE file" (though there are other formats as well), and casual listeners will recognize it as the scrolling text that you're always happy to see, on the rare times your music player shows it. Little-used and even-less-known, however, is that a single disc can theoretically contain metadata in up to eight different languages; because of the complexity that introduces, no unifying datatype is provided in favour of a function-based interface.

`cdtext.h`

Defines

MIN_CDTEXT_FIELD (removed; identical to minBound :: Field)
MAX_CDTEXT_FIELD (removed; identical to maxBound :: Field)

Types

cdtext_field_t -> Field
- CDTEXT_FIELD_INVALID (removed; handled via Nothing)

cdtext_genre_t -> Genre
- CDTEXT_GENRE_UNUSED (removed; handled via Nothing)
cdtext_lang_t -> Language
- CDTEXT_LANGUAGE_UNKNOWN -> UnknownLanguage
  - Before libcdio 2.1.0: (often effectively removed; handled via Nothing)
- CDTEXT_LANGUAGE_INVALID (removed; handled via Nothing)
- CDTEXT_LANGUAGE_BLOCK_UNUSED (removed; handled via Nothing)
cdtext_t (removed; merged into Cdio objects)

Symbols

cdtext_data_init -> cdTextDataInit
cdtext_destroy (removed; handled via the garbage collector)
cdtext_field2str -> fieldString
cdtext_genre2str -> genreString
cdtext_get (removed; type conversion makes it identical to cdtext_get_const)
cdtext_get_const -> cdTextGet
cdtext_get_first_track -> firstTrack
cdtext_get_genre -> genre
cdtext_get_language -> language
cdtext_get_last_track -> lastTrack
cdtext_init (removed; internal function without much external occasion)
cdtext_lang2str -> languageString
cdtext_list_languages -> listLanguages
cdtext_list_languages_v2 -> listAllLanguages
cdtext_select_language -> selectLanguage
cdtext_set (removed; primarily intended for internal use, and is more limited than would be expected)
cdtext_set_language_index -> selectLanguageIndex
cdtext_str2lang -> parseLanguage

Sound.Libcdio.Read.CdText

While similar functionality is provided, the Sound.Libcdio.Read.CdText is written as a separate monadic interface rather than in the Cdio-bound style used here.

cdTextDataInit -> parseCdText
cdTextGet -> discId, snd genre, and info
genre -> fst genre
listAllLanguages -> languages
listLanguages (removed; obsolete and imprecise)
selectLanguage -> withLanguage
selectLanguageIndex -> withIndex

Synopsis

data Cdio
data Field
- = Title
- | Performer
- | Songwriter
- | Composer
- | Message
- | Arranger
- | Isrc
- | UpcEan
- | GenreName
- | DiscId
data Genre
- = Undefined
- | AdultContemporary
- | AltRock
- | Childrens
- | Classic
- | ChristianContemporary
- | Country
- | Dance
- | EasyListening
- | Erotic
- | Folk
- | Gospel
- | HipHop
- | Jazz
- | LatinMusic
- | Musical
- | NewAge
- | Opera
- | Operetta
- | Pop
- | Rap
- | Reggae
- | Rock
- | RhythmAndBlues
- | SoundEffects
- | Soundtrack
- | SpokenWord
- | WorldMusic
data Language
- = UnknownLanguage
- | Albanian
- | Breton
- | Catalan
- | Croatian
- | Welsh
- | Czech
- | Danish
- | German
- | English
- | Spanish
- | Esperanto
- | Estonian
- | Basque
- | Faroese
- | French
- | Frisian
- | Irish
- | Gaelic
- | Galician
- | Icelandic
- | Italian
- | Lappish
- | Latin
- | Latvian
- | Luxembourgian
- | Lithuanian
- | Hungarian
- | Maltese
- | Dutch
- | Norwegian
- | Occitan
- | Polish
- | Portuguese
- | Romanian
- | Romansh
- | Serbian
- | Slovak
- | Slovenian
- | Finnish
- | Swedish
- | Turkish
- | Flemish
- | Wallon
- | Zulu
- | Vietnamese
- | Uzbek
- | Urdu
- | Ukrainian
- | Thai
- | Telugu
- | Tatar
- | Tamil
- | Tadzhik
- | Swahili
- | SrananTongo
- | Somali
- | Sinhalese
- | Shona
- | SerboCroatian
- | Ruthenian
- | Russian
- | Quechua
- | Pushtu
- | Punjabi
- | Persian
- | Papamiento
- | Oriya
- | Nepali
- | Ndebele
- | Marathi
- | Moldavian
- | Malaysian
- | Malagasay
- | Macedonian
- | Laotian
- | Korean
- | Khmer
- | Kazakh
- | Kannada
- | Japanese
- | Indonesian
- | Hindi
- | Hebrew
- | Hausa
- | Gurani
- | Gujurati
- | Greek
- | Georgian
- | Fulani
- | Dari
- | Churash
- | Chinese
- | Burmese
- | Bulgarian
- | Bengali
- | Bielorussian
- | Bambora
- | Azerbaijani
- | Assamese
- | Armenian
- | Arabic
- | Amharic
fieldString :: Field -> String
languageString :: Language -> String
parseLanguage :: String -> Maybe Language
genreString :: Genre -> String
cdTextDataInit :: ByteString -> IO (Maybe Cdio)
listLanguages :: Cdio -> IO [Language]
listAllLanguages :: Cdio -> IO [Maybe Language]
selectLanguage :: Cdio -> Language -> IO Bool
selectLanguageIndex :: Cdio -> Word -> IO Bool
cdTextGet :: Cdio -> Field -> Maybe Track -> IO (Maybe String)
genre :: Cdio -> IO (Maybe Genre)
language :: Cdio -> IO (Maybe Language)
firstTrack :: Cdio -> IO (Maybe Track)
lastTrack :: Cdio -> IO (Maybe Track)

Types

data Cdio #

A particular disc reading/writing device, along with the data contained on the loaded disc. Note well that this is always a mutable object, and is not thread-safe; moreover, any function this is passed to may wind up silently modifying the data.

data Field #

Constructors

Title
Performer
Songwriter
Composer
Message
Arranger
Isrc
UpcEan
GenreName
DiscId

Instances

Instances details

Bounded Field #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods minBound :: Field # maxBound :: Field #
Enum Field #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods succ :: Field -> Field # pred :: Field -> Field # toEnum :: Int -> Field # fromEnum :: Field -> Int # enumFrom :: Field -> [Field] # enumFromThen :: Field -> Field -> [Field] # enumFromTo :: Field -> Field -> [Field] # enumFromThenTo :: Field -> Field -> Field -> [Field] #
Eq Field #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods (==) :: Field -> Field -> Bool # (/=) :: Field -> Field -> Bool #
Ord Field #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods compare :: Field -> Field -> Ordering # (<) :: Field -> Field -> Bool # (<=) :: Field -> Field -> Bool # (>) :: Field -> Field -> Bool # (>=) :: Field -> Field -> Bool # max :: Field -> Field -> Field # min :: Field -> Field -> Field #
Read Field #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods readsPrec :: Int -> ReadS Field # readList :: ReadS [Field] # readPrec :: ReadPrec Field # readListPrec :: ReadPrec [Field] #
Show Field #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods showsPrec :: Int -> Field -> ShowS # show :: Field -> String # showList :: [Field] -> ShowS #

data Genre #

Genres recognized in the CD Text standard.

Instances

Instances details

Bounded Genre #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods minBound :: Genre # maxBound :: Genre #
Enum Genre #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods succ :: Genre -> Genre # pred :: Genre -> Genre # toEnum :: Int -> Genre # fromEnum :: Genre -> Int # enumFrom :: Genre -> [Genre] # enumFromThen :: Genre -> Genre -> [Genre] # enumFromTo :: Genre -> Genre -> [Genre] # enumFromThenTo :: Genre -> Genre -> Genre -> [Genre] #
Eq Genre #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods (==) :: Genre -> Genre -> Bool # (/=) :: Genre -> Genre -> Bool #
Ord Genre #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods compare :: Genre -> Genre -> Ordering # (<) :: Genre -> Genre -> Bool # (<=) :: Genre -> Genre -> Bool # (>) :: Genre -> Genre -> Bool # (>=) :: Genre -> Genre -> Bool # max :: Genre -> Genre -> Genre # min :: Genre -> Genre -> Genre #
Read Genre #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods readsPrec :: Int -> ReadS Genre # readList :: ReadS [Genre] # readPrec :: ReadPrec Genre # readListPrec :: ReadPrec [Genre] #
Show Genre #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods showsPrec :: Int -> Genre -> ShowS # show :: Genre -> String # showList :: [Genre] -> ShowS #

data Language #

Written languages recognized in the CD Text standard.

Constructors

UnknownLanguage
Albanian
Breton
Catalan
Croatian
Welsh
Czech
Danish
German
English
Spanish
Esperanto
Estonian
Basque
Faroese
French
Frisian
Irish
Gaelic
Galician
Icelandic
Italian
Lappish
Latin
Latvian
Luxembourgian
Lithuanian
Hungarian
Maltese
Dutch
Norwegian
Occitan
Polish
Portuguese
Romanian
Romansh
Serbian
Slovak
Slovenian
Finnish
Swedish
Turkish
Flemish
Wallon
Zulu
Vietnamese
Uzbek
Urdu
Ukrainian
Thai
Telugu
Tatar
Tamil
Tadzhik
Swahili
SrananTongo
Somali
Sinhalese
Shona
SerboCroatian
Ruthenian
Russian
Quechua
Pushtu
Punjabi
Persian
Papamiento
Oriya
Nepali
Ndebele
Marathi
Moldavian
Malaysian
Malagasay
Macedonian
Laotian
Korean
Khmer
Kazakh
Kannada
Japanese
Indonesian
Hindi
Hebrew
Hausa
Gurani
Gujurati
Greek
Georgian
Fulani
Dari
Churash
Chinese
Burmese
Bulgarian
Bengali
Bielorussian
Bambora
Azerbaijani
Assamese
Armenian
Arabic
Amharic

Instances

Instances details

Bounded Language #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods minBound :: Language # maxBound :: Language #
Enum Language #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods succ :: Language -> Language # pred :: Language -> Language # toEnum :: Int -> Language # fromEnum :: Language -> Int # enumFrom :: Language -> [Language] # enumFromThen :: Language -> Language -> [Language] # enumFromTo :: Language -> Language -> [Language] # enumFromThenTo :: Language -> Language -> Language -> [Language] #
Eq Language #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods (==) :: Language -> Language -> Bool # (/=) :: Language -> Language -> Bool #
Ord Language #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods compare :: Language -> Language -> Ordering # (<) :: Language -> Language -> Bool # (<=) :: Language -> Language -> Bool # (>) :: Language -> Language -> Bool # (>=) :: Language -> Language -> Bool # max :: Language -> Language -> Language # min :: Language -> Language -> Language #
Read Language #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods readsPrec :: Int -> ReadS Language # readList :: ReadS [Language] # readPrec :: ReadPrec Language # readListPrec :: ReadPrec [Language] #
Show Language #
Instance details Defined in Foreign.Libcdio.Types.Enums Methods showsPrec :: Int -> Language -> ShowS # show :: Language -> String # showList :: [Language] -> ShowS #

Description

fieldString :: Field -> String #

Describe the type of data in a human-readable manner, as opposed to the machine representation returned by the Show instance.

languageString :: Language -> String #

Return a canonical English name of the given language, as opposed to the machine representation returned by the Show instance.

parseLanguage :: String -> Maybe Language #

Transform a string returned by languageString back into its Language representation.

Before libcdio 2.1.0: Always returns Nothing

genreString :: Genre -> String #

Return a canonical English name of the given genre, as opposed to the machine representation returned by the Show instance.

Management

cdTextDataInit :: ByteString -> IO (Maybe Cdio) #

Read binary CD-TEXT data into a structured datatype.

Note that binary CdText dumps will frequently include four bytes at the beginning indicating the size of the file; this implementation expects that those bytes are not included. If your dump does include them, drop 4 before passing the ByteString to this function.

Before libcdio 0.94: Always returns Nothing

listLanguages :: Cdio -> IO [Language] #

Retrieve the languages included in the disc metadata. Note that this does not save the index position or any duplicate language blocks (if that is desired, see listAllLanguages instead).

listAllLanguages :: Cdio -> IO [Maybe Language] #

Retrieve the languages included in the disc metadata, in the order they occur, and respecting any empty language blocks if there's a valid language after them (empty blocks at the end are cleaned away).

Before libcdio 2.1.0: Acts as listLanguages

selectLanguage :: Cdio -> Language -> IO Bool #

Try to set the data associated with the given language as active for future calls to cdTextGet and similar. If passed UnknownLanguage or the CDTEXT does not provide the one requested, selects the first (default) data set instead, and returns False.

selectLanguageIndex :: Cdio -> Word -> IO Bool #

Select the language at the given index of listAllLanguages for future data retrieval. If the index is out of bounds or corresponds to a Nothing in listAllLanguages, the first (default) data set is selected instead and 'False is returned.

Access

cdTextGet :: Cdio -> Field -> Maybe Track -> IO (Maybe String) #

Attempt to retrieve the value of a given field from the disc (if Nothing) or track (if Just) metadata, in the currently-active language. Note that GenreName and DiscId will always refer to the disc-level data.

genre :: Cdio -> IO (Maybe Genre) #

The machine-readable genre describing the music on this disc. For any associated human-readable name or subgenre, use cdTextGet c GenreName Nothing.

language :: Cdio -> IO (Maybe Language) #

Indicate which language results will (currently) be returned in. See selectLanguage to change this.

firstTrack :: Cdio -> IO (Maybe Track) #

The earliest track with any associated metadata in the current language. Note that this may differ from minTrack.

lastTrack :: Cdio -> IO (Maybe Track) #

The final track with any associated metadata in the current language. Note that this may differ from maxTrack.

Undefined
AdultContemporary
AltRock
Childrens
Classic
ChristianContemporary
Country
Dance
EasyListening
Erotic
Folk
Gospel
HipHop
Jazz
LatinMusic
Musical
NewAge
Opera
Operetta
Pop
Rap
Reggae
Rock
RhythmAndBlues
SoundEffects
Soundtrack
SpokenWord
WorldMusic