Begin documenting the soundfile module

docs/source/index.rst

@@ -17,6 +17,7 @@ API documentation
     :maxdepth: 2
 
     timeseries
+    soundfile
     spectral
     core
 

docs/source/soundfile.rst

@@ -0,0 +1,10 @@
+Soundfile
+=========
+.. automodule:: zounds.soundfile
+.. currentmodule:: zounds.soundfile
+
+.. autoclass:: AudioStream
+
+.. autoclass:: Resampler
+
+.. autoclass:: OggVorbis

zounds/soundfile/__init__.py

@@ -1,3 +1,8 @@
+"""
+The soundfile module introduces :class:`featureflow.Node` subclasses that know
+how to process low-level audio samples and common audio encodings.
+"""
+
 from audio_metadata import MetaData, AudioMetaDataEncoder, FreesoundOrgConfig
 
 from ogg_vorbis import \

zounds/soundfile/audiostream.py

@@ -7,6 +7,54 @@
 
 
 class AudioStream(Node):
+    """
+    `AudioStream` expects to process a raw stream of bytes (e.g. one
+    produced by :class:`featureflow.ByteStream`) and produces chunks of
+    :class:`~zounds.timeseries.AudioSamples`
+
+    Args:
+        sum_to_mono (bool): True if this node should return a
+            :class:`~zounds.timeseries.AudioSamples` instance with a single
+            channel
+        needs (Feature): a processing node that produces a byte stream (e.g.
+            :class:`~featureflow.ByteStream`
+
+    Here's how'd you typically see :class:`AudioStream` used in a processing
+    graph.
+
+    .. code:: python
+
+        import featureflow as ff
+        import zounds
+
+
+        @zounds.simple_in_memory_settings
+        class Document(ff.BaseModel):
+            meta = ff.JSONFeature(
+                zounds.MetaData,
+                store=True,
+                encoder=zounds.AudioMetaDataEncoder)
+
+            raw = ff.ByteStreamFeature(
+                ff.ByteStream,
+                chunksize=2 * 44100 * 30 * 2,
+                needs=meta,
+                store=False)
+
+            pcm = zounds.AudioSamplesFeature(
+                zounds.AudioStream,
+                needs=raw,
+                store=True)
+
+
+        synth = zounds.NoiseSynthesizer(zounds.SR11025())
+        samples = synth.synthesize(zounds.Seconds(10))
+        raw_bytes = samples.encode()
+        _id = Document.process(meta=raw_bytes)
+        doc = Document(_id)
+        print doc.pcm.__class__  # returns an AudioSamples instance
+    """
+
     def __init__(
             self,
             sum_to_mono=True,

zounds/soundfile/resample.py

@@ -114,6 +114,60 @@ def __call__(self, insamples, end_of_input=False):
 
 
 class Resampler(Node):
+    """
+    `Resampler` expects to process :class:`~zounds.timeseries.AudioSamples`
+    instances (e.g., those produced by a :class:`AudioStream` node), and will
+    produce a new stream of :class:`AudioSamples` at a new sampling rate.
+
+    Args:
+        samplerate (AudioSampleRate): the desired sampling rate.  If none is
+            provided, the default is :class:`~zounds.timeseries.SR44100`
+        needs (Feature): a processing node that produces
+            :class:`~zounds.timeseries.AudioSamples`
+
+
+    Here's how you'd typically see :class:`Resampler` used in a processing
+    graph.
+
+    .. code:: python
+
+        import featureflow as ff
+        import zounds
+
+
+        @zounds.simple_in_memory_settings
+        class Document(ff.BaseModel):
+            meta = ff.JSONFeature(
+                zounds.MetaData,
+                store=True,
+                encoder=zounds.AudioMetaDataEncoder)
+
+            raw = ff.ByteStreamFeature(
+                ff.ByteStream,
+                chunksize=2 * 44100 * 30 * 2,
+                needs=meta,
+                store=False)
+
+            pcm = zounds.AudioSamplesFeature(
+                zounds.AudioStream,
+                needs=raw,
+                store=True)
+
+            resampled = zounds.AudioSamplesFeature(
+                zounds.Resampler,
+                samplerate=zounds.SR22050(),
+                needs=pcm,
+                store=True)
+
+
+        synth = zounds.NoiseSynthesizer(zounds.SR11025())
+        samples = synth.synthesize(zounds.Seconds(10))
+        raw_bytes = samples.encode()
+        _id = Document.process(meta=raw_bytes)
+        doc = Document(_id)
+        print doc.pcm.samplerate.__class__.__name__  # SR11025
+        print doc.resampled.samplerate.__class__.__name__  # SR22050
+    """
     def __init__(self, samplerate=None, needs=None):
         super(Resampler, self).__init__(needs=needs)
         self._samplerate = samplerate or SR44100()