Merge branch 'master' into maint-reds

README.md

@@ -7,9 +7,9 @@
 # wavinfo
 
 The `wavinfo` package allows you to probe WAVE and [RF64/WAVE files][eburf64] 
-and extract extended metadata, with an emphasis on film, video and 
-professional music production.
-
+and extract extended metadata. `wavinfo` has an emphasis on film, video and 
+professional music production but aspires to be the encyclopedic and final 
+source for all WAVE file metadata.
 
 ## Metadata Support
 
@@ -24,12 +24,15 @@ professional music production.
 * [iXML][ixml] production recorder metadata, including project, scene, and 
   take tags, recorder notes and file family information.
   * iXML `STEINBERG` sound library attributes.
-* Wave embedded cue markers, cue marker labels, notes and timed ranges as used
+* Wave embedded [cue markers][cues], cue marker labels, notes and timed ranges as used
   by Zoom, iZotope RX, etc.
 * Most of the common [RIFF INFO][info-tags] metadata fields.
-* The __wav format__ is also parsed, so you can access the basic sample rate 
+* The [wav format][format] is also parsed, so you can access the basic sample rate 
   and channel count information.
 
+
+[format]:https://wavinfo.readthedocs.io/en/latest/classes.html#wavinfo.wave_reader.WavAudioFormat
+[cues]:https://wavinfo.readthedocs.io/en/latest/scopes/cue.html
 [bext]:https://wavinfo.readthedocs.io/en/latest/scopes/bext.html
 [smpte_330m2011]:https://wavinfo.readthedocs.io/en/latest/scopes/bext.html#wavinfo.wave_bext_reader.WavBextReader.umid
 [adm]:https://wavinfo.readthedocs.io/en/latest/scopes/adm.html
@@ -60,6 +63,12 @@ The package also installs a shell command:
 $ wavinfo test_files/A101_1.WAV
 ```
 
+## Contributions!
+
+Any new or different kind of metadata you find, or any 
+new or different use of exising metadata you encounter, please submit
+an Issue or Pull Request!
+
 ## Other Resources
 
 * For other file formats and ID3 decoding, 

docs/source/scopes/cue.rst

@@ -29,3 +29,12 @@ Class Reference
 
 .. autoclass:: wavinfo.wave_cues_reader.WavCuesReader
    :members:
+
+.. autoclass:: wavinfo.wave_cues_reader.CueEntry
+   :members:
+
+.. autoclass:: wavinfo.wave_cues_reader.LabelEntry
+   :members:
+
+.. autoclass:: wavinfo.wave_cues_reader.NoteEntry
+   :members:

wavinfo/wave_cues_reader.py

@@ -98,7 +98,14 @@
 
 
 class CueEntry(NamedTuple):
+    """
+    A ``cue`` element structure.
+    """
+    #: Cue "name" or id number 
     name: int
+    #: Cue position, as a frame count in the play order of the WAVE file. In 
+    #: principle this can be affected by playlists and ``wavl`` chunk 
+    #: placement.
     position: int
     chunk_id: bytes
     chunk_start: int
@@ -125,6 +132,9 @@ def read(cls, data: bytes) -> 'CueEntry':
 
 
 class LabelEntry(NamedTuple):
+    """
+    A ``labl`` structure.
+    """
     name: int
     text: str
 
@@ -138,6 +148,9 @@ def read(cls, data: bytes, encoding: str):
 
 
 class RangeLabel(NamedTuple):
+    """
+    A ``ltxt`` structure.
+    """
     name: int
     length: int
     purpose: str
@@ -164,9 +177,17 @@ def read(cls, data: bytes, fallback_encoding: str):
 
 @dataclass
 class WavCuesReader:
+
+    #: Every ``cue`` entry in the file
     cues: List[CueEntry]
+
+    #: Every ``labl`` in the file
     labels: List[LabelEntry]
+
+    #: Every ``ltxt`` in the file
     ranges: List[RangeLabel]
+
+    #: Every ``note`` in the file
     notes: List[NoteEntry]
 
     @classmethod
@@ -264,10 +285,4 @@ def to_dict(self) -> Dict[str, Any]:
                 retval[n]['length'] = r 
 
         return retval 
-        # return dict(cues=[c._asdict() for c in self.cues],
-        #             labels=[l._asdict() for l in self.labels],
-        #             ranges=[r._asdict() for r in self.ranges],
-        #             notes=[n._asdict() for n in self.notes])
-
-