New macros for CD-TEXT genre and language names

cdrskin/cdrskin_timestamp.h

@@ -1 +1 @@
-#define Cdrskin_timestamP "2011.12.12.092602"
+#define Cdrskin_timestamP "2011.12.12.164452"

doc/cdtext.txt

@@ -3,11 +3,14 @@
 
 Guided by Leon Merten Lohse       via  libcdio-devel@gnu.org
 by reading           mmc3r10g.pdf from http://www.t10.org/ftp/t10/drafts/mmc3/
-by reading           tech3264.pdf from http://tech.ebu.ch/docs/tech/
 by docs and results of cdtext.zip from http://www.sonydadc.com/file/
 by reading source of      libcdio from http://www.gnu.org/s/libcdio
 which quotes source of   cdrecord from ftp://ftp.berlios.de/pub/cdrecord/alpha
 
+Language codes were learned from http://tech.ebu.ch/docs/tech/tech3264.pdf
+Genre codes were learned from libcdio and confirmed by
+http://helpdesk.audiofile-engineering.com/index.php?pg=kb.page&id=123
+
 For libburnia-project.org by Thomas Schmitt <scdbackup@gmx.net>
 
 Content:
@@ -61,16 +64,19 @@ Content specification of particular pack types:
 
 Pack types 0x80 to 0x85 and 0x8e contain 0-terminated cleartext. If double byte
 characters are used, then two 0-bytes terminate the cleartext.
-The meaning of 0x80 to 0x85 should be clear by above list.
+The meaning of 0x80 to 0x85 should be clear by above list. They are encoded
+according to the Character Code of their block. Either as ISO-8859-1 single
+byte characters, or as 7-bit ASCII single byte characters, or as MS-JIS double
+byte characters.
 More info to 0x8e is given below.
 
 Pack type 0x86 (Disc Identification) is documented by Sony as "Catalog Number:
 (use ASCII Code) Catalog Number of the album". So it is not really binary
-but might be non-printable.
+but might be non-printable, and should contain only bytes with bit7 = 0.
 
 Pack type 0x87 contains 2 binary bytes, followed by 0-terminated cleartext.
 The two binary bytes form a big-endian index to the following list.
-  0x0000 = "Not Used"
+  0x0000 = "Not Used" (Sony prescribes to use this if no genre applies)
   0x0001 = "Not Defined"
   0x0002 = "Adult Contemporary"
   0x0003 = "Alternative Rock"
@@ -99,7 +105,7 @@ The two binary bytes form a big-endian index to the following list.
   0x001a = "Spoken Word"
   0x001b = "World Music"
 Sony documents the cleartext part as "Genre information that would supplement
-the Genre Code, such as 'USA Rock music in the 60s'".
+the Genre Code, such as 'USA Rock music in the 60s'". Always ASCII encoded.
 
 Pack type 0x88 records information from the CDs Table of Content, as of
 READ PMA/TOC/ATIP Format 0010b (mmc5r03c.pdf, table 490 TOC Track Descriptor
@@ -113,9 +119,10 @@ an example of this pack type.
 Pack type 0x8d is documented by Sony as "Closed Information: (use 8859-1 Code)
 Any information can be recorded on disc as memorandum. Information in this
 field will not be read by CD TEXT players available to the public."
+Always ISO-8859-1 encoded.
 
 Pack type 0x8e is documented by Sony as "UPC/EAN Code (POS Code) of the album.
-This field typically consists of 13 characters."
+This field typically consists of 13 characters." Always ASCII encoded.
 
 Pack type 0x8f summarizes the whole list of text packs of a block.
 See below, Format of CD-TEXT packs, for details.
@@ -229,10 +236,10 @@ language code of all blocks.
 The payload bytes of three 0x8f packs form a 36 byte record. The track number
 bytes of the three packs have the values 0, 1, 2.
     Byte :
-       0 : Character code:
+       0 : Character code for pack types 0x80 to 0x85:
            0x00 = ISO-8859-1
            0x01 = 7 bit ASCII
-           0x80 = Kanji (japanese)
+           0x80 = MS-JIS (japanese Kanji, double byte characters)
        1 : Number of first track
        2 : Number of last track
        3 : libcdio source states: "cd-text information copyright byte"
@@ -313,6 +320,7 @@ bytes of the three packs have the values 0, 1, 2.
            0x5c = Oriya
            0x5d = Nepali
            0x5e = Ndebele
+           0x5f = Marathi
            0x60 = Moldavian
            0x61 = Malaysian
            0x62 = Malagasay

libburn/libburn.h

@@ -1887,20 +1887,15 @@ int burn_session_remove_track(struct burn_session *s, struct burn_track *t);
     Copyright byte value can be
       0x00 = not copyrighted
       0x03 = copyrighted
-    Language Code value can be
+    Language Code value will typically be 0x09 = English or 0x69 = Japanese.
-      0x00 = Unknown   0x04 = Croatian  0x08 = German   0x09 = English
+    See below macros BURN_CDTEXT_LANGUAGES_0X00 and BURN_CDTEXT_LANGUAGES_0X45,
-      0x0a = Spanish   0x0f = French    0x15 = Italian  0x27 = Finnish
+    but be aware that many of these codes have never been seen on CD, and that
-      0x29 = Turkish   0x69 = Japanese
+    many of them do not have a character representation among the above
-    or other latin alphabet codes from EBU Tech 3264, appendix 3, like
+    Character Codes. 
-      0x06 = Czech     0x07 = Danish    0x11 = Irish    0x17 = Latin
-      0x1b = Hungarian 0x1d = Dutch     0x20 = Polish   0x21 = Portuguese
-    as well as such where character representation is unclear
-      0x56 = Russian   0x6b = Hindi     0x6c = Hebrew   0x70 = Greek
-      0x75 = Chinese   0x77 = Bulgarian 0x7e = Arabic   0x7f = Amharic
     Default is 0x09 = English for block 0 and 0x00 = Unknown for block 1 to 7.
     Copyright and Character Code are 0x00 for all blocks by default.
-    For a detailed description of these parameters see file
+    See also file doc/cdtext.txt, "Format of a CD-TEXT packs array",
-    doc/cdtext.txt, "Format of a CD-TEXT packs array", "Pack type 0x8f".
+    "Pack type 0x8f".
 
     Parameter value -1 leaves the current setting of the session parameter
     unchanged.
@@ -1916,6 +1911,52 @@ int burn_session_set_cdtext_par(struct burn_session *s,
                                 int char_codes[8], int copyrights[8],
                                 int languages[8], int flag);
 
+/** This is the first list of languages sorted by their Language codes,
+    which start at 0x00.  They stem from from EBU Tech 3264, appendix 3.
+    E.g. language 0x00 is "Unknown", 0x08 is "German", 0x10 is "Frisian",
+    0x18 is "Latvian", 0x20 is "Polish", 0x28 is "Swedish", 0x2b is "Wallon".
+    See also file doc/cdtext.txt.
+    @since 1.2.0
+*/
+#define BURN_CDTEXT_LANGUAGES_0X00 \
+        "Unknown", "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" 
+
+/** This is the second list of languages sorted by their Language codes,
+    which start at 0x45.  They stem from from EBU Tech 3264, appendix 3.
+    E.g. language 0x45 is "Zulu", 0x50 is "Sranan Tongo", 0x58 is "Pushtu",
+    0x60 is "Moldavian", 0x68 is "Kannada", 0x70 is "Greek", 0x78 is "Bengali",
+    0x7f is "Amharic".
+    See also file doc/cdtext.txt.
+    @since 1.2.0
+*/
+#define BURN_CDTEXT_LANGUAGES_0X45 \
+                 "Zulu", "Vietnamese", "Uzbek", \
+        "Urdu", "Ukrainian", "Thai", "Telugu", \
+        "Tatar", "Tamil", "Tadzhik", "Swahili", \
+        "Sranan Tongo", "Somali", "Sinhalese", "Shona", \
+        "Serbo-croat", "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"
+
+
 /* ts B11206 */
 /** Obtain the current settings as of burn_session_set_cdtext_par() resp.
     by default.
@@ -1957,17 +1998,20 @@ int burn_session_get_cdtext_par(struct burn_session *s,
                         Names are recognized uppercase and lowercase.
     @param payload      Text or binary bytes. The data will be copied to
                         session-internal memory.
-                        Pack types 0x80 to 0x85 and 0x8e contain 0-terminated
+                        Pack types 0x80 to 0x85 contain 0-terminated cleartext
-                        cleartext. If double byte characters are used, then
+                        encoded according to the block's Character Code.
-                        two 0-bytes terminate the cleartext.
+                        If double byte characters are used, then two 0-bytes
+                        terminate the cleartext.
                         Pack type 0x86 is 0-terminated ASCII cleartext.
                         Pack type 0x87 consists of two byte big-endian
-                        Genre code, and 0-terminated genre cleartext.
+                        Genre code (see below BURN_CDTEXT_GENRE_LIST), and
+                        0-terminated ASCII cleartext of genre description.
                         Pack type 0x88 mirrors the session table-of-content.
                         Pack type 0x89 is not understood yet.
                         Pack types 0x8a to 0x8c are reserved.
-                        Pack type 0x8e contains cleartext which is not to be
+                        Pack type 0x8d contains ISO-8859-1 cleartext which is
-                        shown by commercial audio CD players.
+                        not to be shown by commercial audio CD players.
+                        Pack type 0x8e is ASCII cleartext with UPC/EAN code.
     @pram length        Number of bytes in payload. Including terminating
                         0-bytes.
     @param flag         Bitfield for control purposes.
@@ -1980,6 +2024,23 @@ int burn_session_set_cdtext(struct burn_session *s, int block,
                             int pack_type, char *pack_type_name,
                             unsigned char *payload, int length, int flag);
 
+
+/** This is the list of Genres sorted by their Genre codes.
+    E.g. genre code 0x0000 is "No Used", 0x0008 is "Dance, 0x0010 is "Musical",
+    0x0018 is "Rhythm & Blues", 0x001b is "World Music".
+    See also file doc/cdtext.txt.
+    @since 1.2.0
+*/
+#define BURN_CDTEXT_GENRE_LIST \
+        "Not Used", "Not Defined", "Adult Contemporary", "Alternative Rock", \
+        "Childrens Music", "Classical", "Contemporary Christian", "Country", \
+        "Dance", "Easy Listening", "Erotic", "Folk", \
+        "Gospel", "Hip Hop", "Jazz", "Latin", \
+        "Musical", "New Age", "Opera", "Operetta", \
+        "Pop Music", "Rap", "Reggae", "Rock Music", \
+        "Rhythm & Blues", "Sound Effects", "Spoken Word", "World Music"
+
+
 /* ts B11206 */
 /** Obtain a CD-TEXT attribute that was set by burn_session_set_cdtext()
     @param s            Session to inquire
@@ -2014,8 +2075,10 @@ int burn_session_get_cdtext(struct burn_session *s, int block,
                         Dispose by free() when no longer needed.
     @param num_packs    Will return the number of 18 byte text packs.
     @param flag         Bitfield for control purposes.
-                        bit0= do not produce CD-TEXT packs, but return number
+                        bit0= do not return generated CD-TEXT packs,
-                              of packs. This happens also if
+                              but check whether production would work and
+                              indicate the number of packs by the call return
+                              value. This happens also if
                               (text_packs == NULL || num_packs == NULL).
     @return             Without flag bit0: > 0 is success, <= 0 failure
                         With flag bit0: > 0 is number of packs,
@@ -2072,6 +2135,9 @@ int burn_track_set_byte_swap(struct burn_track *t, int swap_source_bytes);
     gets generated, which has the same block number and pack type. In this
     case, each track should have such a CD-TEXT attribute, too.
     See burn_session_set_cdtext().
+    Be cautious not to exceed the maximum number of 253 payload packs per
+    language block. Use burn_cdtext_from_session() to learn whether a valid
+    array of CD-TEXT packs can be generated from your attributes.
     @param t            Track where to attach CD-TEXT attribute.
     @param block        Number of the language block in which the attribute
                         shall appear. Possible values: 0 to 7.

libburn/write.c

@@ -1073,6 +1073,8 @@ ex:;
 	if (ret <= 0 || (flag & 1)) {
 		if (ret > 0)
 			ret = crs.num_packs;
+		else if (flag & 1)
+			ret = -1;
 		BURN_FREE_MEM(crs.packs);
 	} else if (crs.num_packs > 0) {
 		*text_packs = crs.packs;