diff --git a/README.rst b/README.rst index 7d16a34..5556675 100644 --- a/README.rst +++ b/README.rst @@ -36,16 +36,8 @@ This is easily achieved by downloading or individual libraries can be installed using `circup `_. -.. todo:: Describe the Adafruit product this library works with. For PCBs, you can also add the -image from the assets folder in the PCB's GitHub repo. - -`Purchase one from the Adafruit shop `_ Installing from PyPI ===================== -.. note:: This library is not available on PyPI yet. Install documentation is included - as a standard element. Stay tuned for PyPI availability! - -.. todo:: Remove the above note if PyPI version is/will be available at time of release. On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from PyPI `_. @@ -96,8 +88,15 @@ Or the following command to update an existing version: Usage Example ============= -.. todo:: Add a quick, simple example. It and other examples should live in the -examples folder and be included in docs/examples.rst. +.. code-block:: python + + import adafruit_wave + + with adafruit_wave.open("sample.wav") as w: + print(w.getsampwidth()) + print(w.getnchannels()) + print(w.getcomptype()) + print(list(memoryview(w.readframes(100)).cast("h"))) Documentation ============= diff --git a/adafruit_wave.py b/adafruit_wave.py index 9dd09cb..b2f95c5 100644 --- a/adafruit_wave.py +++ b/adafruit_wave.py @@ -18,76 +18,6 @@ Implementation Notes * Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads -Usage. - -Reading WAVE files: - f = wave.open(file, 'r') -where file is either the name of a file or an open file pointer. -The open file pointer must have methods read(), seek(), and close(). -When the setpos() and rewind() methods are not used, the seek() -method is not necessary. - -This returns an instance of a class with the following public methods: - getnchannels() -- returns number of audio channels (1 for - mono, 2 for stereo) - getsampwidth() -- returns sample width in bytes - getframerate() -- returns sampling frequency - getnframes() -- returns number of audio frames - getcomptype() -- returns compression type ('NONE' for linear samples) - getcompname() -- returns human-readable version of - compression type ('not compressed' linear samples) - getparams() -- returns a namedtuple consisting of all of the - above in the above order - getmarkers() -- returns None (for compatibility with the - aifc module) - getmark(id) -- raises an error since the mark does not - exist (for compatibility with the aifc module) - readframes(n) -- returns at most n frames of audio - rewind() -- rewind to the beginning of the audio stream - setpos(pos) -- seek to the specified position - tell() -- return the current position - close() -- close the instance (make it unusable) -The position returned by tell() and the position given to setpos() -are compatible and have nothing to do with the actual position in the -file. -The close() method is called automatically when the class instance -is destroyed. - -Writing WAVE files: - f = wave.open(file, 'w') -where file is either the name of a file or an open file pointer. -The open file pointer must have methods write(), tell(), seek(), and -close(). - -This returns an instance of a class with the following public methods: - setnchannels(n) -- set the number of channels - setsampwidth(n) -- set the sample width - setframerate(n) -- set the frame rate - setnframes(n) -- set the number of frames - setcomptype(type, name) - -- set the compression type and the - human-readable compression type - setparams(tuple) - -- set all parameters at once - tell() -- return current position in output file - writeframesraw(data) - -- write audio frames without patching up the - file header - writeframes(data) - -- write audio frames and patch up the file header - close() -- patch up the file header and close the - output file -You should set the parameters before the first writeframesraw or -writeframes. The total number of frames does not need to be set, -but when it is set to the correct value, the header does not have to -be patched up. -It is best to first set all parameters, perhaps possibly the -compression type, and then write audio frames using writeframesraw. -When all frames have been written, either call writeframes(b'') or -close() to patch up the sizes in the header. -The close() method is called automatically when the class instance -is destroyed. - """ # pylint: disable=missing-class-docstring,redefined-outer-name,missing-function-docstring,invalid-name,import-outside-toplevel,too-many-instance-attributes,consider-using-with,no-self-use,redefined-builtin,not-callable,unused-variable,attribute-defined-outside-init,too-many-public-methods,no-else-return @@ -176,6 +106,7 @@ class Chunk: def read(self, size=-1): """Read at most size bytes from the chunk. + If size is omitted or negative, read until the end of the chunk. """ @@ -197,6 +128,7 @@ class Chunk: def skip(self): """Skip the rest of the chunk. + If you are not interested in the contents of the chunk, this method should be called so that the file points to the start of the next chunk. @@ -236,36 +168,6 @@ _wave_params = namedtuple( class Wave_read: - """Variables used in this class: - - These variables are available to the user though appropriate - methods of this class: - _file -- the open file with methods read(), close(), and seek() - set through the __init__() method - _nchannels -- the number of audio channels - available through the getnchannels() method - _nframes -- the number of audio frames - available through the getnframes() method - _sampwidth -- the number of bytes per audio sample - available through the getsampwidth() method - _framerate -- the sampling frequency - available through the getframerate() method - _comptype -- the AIFF-C compression type ('NONE' if AIFF) - available through the getcomptype() method - _compname -- the human-readable AIFF-C compression type - available through the getcomptype() method - _soundpos -- the position in the audio stream - available through the tell() method, set through the - setpos() method - - These variables are used internally only: - _fmt_chunk_read -- 1 iff the FMT chunk has been read - _data_seek_needed -- 1 iff positioned correctly in audio - file for readframes() - _data_chunk -- instantiation of a chunk class for the DATA chunk - _framesize -- size of one frame in the file - """ - def initfp(self, file): self._convert = None self._soundpos = 0 @@ -429,31 +331,6 @@ class Wave_read: class Wave_write: - """Variables used in this class: - - These variables are user settable through appropriate methods - of this class: - _file -- the open file with methods write(), close(), tell(), seek() - set through the __init__() method - _comptype -- the AIFF-C compression type ('NONE' in AIFF) - set through the setcomptype() or setparams() method - _compname -- the human-readable AIFF-C compression type - set through the setcomptype() or setparams() method - _nchannels -- the number of audio channels - set through the setnchannels() or setparams() method - _sampwidth -- the number of bytes per audio sample - set through the setsampwidth() or setparams() method - _framerate -- the sampling frequency - set through the setframerate() or setparams() method - _nframes -- the number of audio frames written to the header - set through the setnframes() or setparams() method - - These variables are used internally only: - _datalength -- the size of the audio samples written to the header - _nframeswritten -- the number of frames actually written - _datawritten -- the size of the audio samples actually written - """ - def __init__(self, f): self._i_opened_the_file = None if isinstance(f, str): diff --git a/docs/index.rst b/docs/index.rst index 14491b7..b1f1f3c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,15 +24,9 @@ Table of Contents .. toctree:: :caption: Tutorials -.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave - the toctree above for use later. - .. toctree:: :caption: Related Products -.. todo:: Add any product links here. If there are none, then simply delete this todo and leave - the toctree above for use later. - .. toctree:: :caption: Other Links