Documentation

wavinfo/wave_bext_reader.py

@@ -2,28 +2,12 @@ import struct
 
 class WavBextReader:
     def __init__(self,bext_data,encoding):
-        # description[256]
-
-        # originator[32]
-        # originatorref[32]
-        # originatordate[10]   "YYYY:MM:DD"
-        # originatortime[8]    "HH:MM:SS"
-        # lowtimeref U32
-        # hightimeref U32
-        # version U16
-        #
-        # V1 field
-        # umid[64]
-        #
-        # V2 fields
-        # loudnessvalue S16    (in LUFS*100)
-        # loudnessrange S16    (in LUFS*100)
-        # maxtruepeak   S16    (in dbTB*100)
-        # maxmomentaryloudness S16 (LUFS*100)
-        # maxshorttermloudness S16 (LUFS*100)
-        #
-        # reserved[180]
-        # codinghistory []
+        """
+        Read Broadcast-WAV extended metadata.
+        :param best_data: The bytes-like data.
+        "param encoding: The encoding to use when decoding the text fields of the
+                 BEXT metadata scope. According to EBU Rec 3285 this shall be ASCII.
+        """
         packstring = "<256s"+ "32s" + "32s" + "10s" + "8s" + "QH" + "64s" + "hhhhh" + "180s"
 
         rest_starts = struct.calcsize(packstring)
@@ -39,20 +23,38 @@ class WavBextReader:
             decoded = trimmed.decode(encoding)
             return decoded
 
+        #: Description. A free-text field up to 256 characters long.
         self.description     = sanatize_bytes(unpacked[0])
+        #: Originator. Usually the name of the encoding application, sometimes
+        #: a artist name.
         self.originator      = sanatize_bytes(unpacked[1])
+        #: A unique identifer for the file, a serial number.
         self.originator_ref  = sanatize_bytes(unpacked[2])
+        #: Date of the recording, in the format YYY-MM-DD
         self.originator_date = sanatize_bytes(unpacked[3])
+        #: Time of the recording, in the format HH:MM:SS.
         self.originator_time = sanatize_bytes(unpacked[4])
+        #: The sample offset of the start of the file relative to an
+        #: epoch, usually midnight the day of the recording. 
         self.time_reference  = unpacked[5]
-        self.version         = unpacked[6]
-        self.umid            = None
-        self.loudness_value          = None
-        self.loudness_range          = None
-        self.max_true_peak           = None
-        self.max_momentary_loudness  = None
-        self.max_shortterm_loudness  = None
+        #: A variable-length text field containing a list of processes and
+        #: and conversions performed on the file.
         self.coding_history  = sanatize_bytes(bext_data[rest_starts:])
+        #: BEXT version. 
+        self.version         = unpacked[6]
+        #: SMPTE 330M UMID of this audio file, 64 bytes are allocated though the UMID
+        #: may only be 32 bytes long.
+        self.umid            = None
+        #: EBU R128 Integrated loudness, in LUFS.
+        self.loudness_value          = None
+        #: EBU R128 Loudness rante, in LUFS.
+        self.loudness_range          = None
+        #: True peak level, in dBFS TP
+        self.max_true_peak           = None
+        #: EBU R128 Maximum momentary loudness, in LUFS
+        self.max_momentary_loudness  = None
+        #: EBU R128 Maximum short-term loudness, in LUFS.
+        self.max_shortterm_loudness  = None
 
         if self.version > 0:
             self.umid = unpacked[7]