Skip to content

Add documentation for the class fields #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for the class fields #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 183 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,29 @@ stream_file() instead.
``CaptureDevice (self, input_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Optional[_cffi_backend._CDataBase] = None, callback_periods: int = 0, backends: Optional[List[miniaudio.Backend]] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
> An audio device provided by miniaudio, for audio capture (recording).

> *field* ``buffersize_msec``
> > The size of the audio buffer being held in this capture device.

> *field* ``callback_generator``
> > A callback generator to provide the audio data to. The callback generator should provide the
number of samples it wants to receive, and will receive a ``bytearray`` containing the sample data
for that number of samples.

> *field* ``format``
> > The sample format this capture device produces.

> *field* ``nchannels``
> > The number of audio channels this capture device produces.

> *field* ``running``
> > Whether the device is currently capturing (has been started).

> *field* ``sample_rate``
> > The number of samples this capture device produces per second.

> *field* ``sample_width``
> > The sample width in bytes that this capture device produces.

> *method* ``close (self) ``
> > Halt playback or capture and close down the device. If you use the device as a context manager,
it will be closed automatically.
Expand All @@ -385,12 +408,42 @@ callback generator as raw bytes. (it should already be started before)
``DecodedSoundFile (self, name: str, nchannels: int, sample_rate: int, sample_format: miniaudio.SampleFormat, samples: array.array) ``
> Contains various properties and also the PCM frames of a fully decoded audio file.

> *field* ``duration``
> > The duration of the audio in this file if played back at normal rate, in seconds (as ``float``).

> *field* ``name``
> > The path to the file that was decoded.

> *field* ``nchannels``
> > The number of audio channels that this file contains.

> *field* ``num_frames``
> > The total number of frames contained in this file.

> *field* ``sample_format``
> > The sample format that this file was decoded to, as a ``SampleFormat`` enum.

> *field* ``sample_format_name``
> > A human-readable name for the ``sample_format`` field, as a string.

> *field* ``sample_rate``
> > The number of samples that should be played per second to play this file back at normal rate.

> *field* ``sample_width``
> > The width of the samples that this file was decoded to, in bytes.

> *field* ``samples``
> > The sample data contained in this sound file, as an array of bytes.


*class* ``Devices``

``Devices (self, backends: Optional[List[miniaudio.Backend]] = None) ``
> Query the audio playback and record devices that miniaudio provides

> *field* ``backend``
> > The audio back-end currently being used to record and/or playback audio through the system.

> *method* ``get_captures (self) -> List[Dict[str, Any]]``
> > Get a list of capture devices and some details about them

Expand All @@ -403,6 +456,39 @@ callback generator as raw bytes. (it should already be started before)
``DuplexStream (self, playback_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, playback_channels: int = 2, capture_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, capture_channels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, playback_device_id: Optional[_cffi_backend._CDataBase] = None, capture_device_id: Optional[_cffi_backend._CDataBase] = None, callback_periods: int = 0, backends: Optional[List[miniaudio.Backend]] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
> Joins a capture device and a playback device.

> *field* ``backend``
> > The name of the audio back-end to use for capturing of playing audio through the system.

> *field* ``buffersize_msec``
> > The size of the audio buffers to use for capturing and playing audio, in milliseconds of
playback.

> *field* ``callback_generator``
> > A callback generator to provide the captured audio data to. The callback generator should
provide the number of samples it wants to receive, and will receive a ``bytearray`` containing the
sample data for that number of samples.

> *field* ``capture_channels``
> > The number of channels to be used for recording audio.

> *field* ``capture_format``
> > The sample format to be used for recording audio.

> *field* ``playback_channels``
> > The number of channels to be used for playing audio.

> *field* ``playback_format``
> > The sample format to be used for playing audio.

> *field* ``running``
> > Whether the device is currently capturing and/or playing (has been started).

> *field* ``sample_rate``
> > The number of samples to capture and playback per second.

> *field* ``sample_width``
> > The width of samples to be used for recording audio, in bytes.

> *method* ``close (self) ``
> > Halt playback or capture and close down the device. If you use the device as a context manager,
it will be closed automatically.
Expand All @@ -425,6 +511,25 @@ data. You can also provide a callback to be called when a new stream title is av
downloading of the data from the internet is done in a background thread and it tries to keep a
(small) buffer filled with available data to read.

> *field* ``audio_info``
> > A string of audio info provided by this station, containing e.g. its sample rate, audio quality
and number of channels.

> *field* ``audio_format``
> > The file format that this station streams.

> *field* ``station_genre``
> > The musical genre that this station plays.

> *field* ``station_name``
> > The name of this station.

> *field* ``stream_title``
> > The title of the currently playing track.

> *field* ``url``
> > The URL to the currently playing stream.

> *method* ``close (self) ``
> > Stop the stream, aborting the background downloading.

Expand All @@ -447,6 +552,33 @@ give the file type to a decoder upfront. You can ignore this method then.
``PlaybackDevice (self, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Optional[_cffi_backend._CDataBase] = None, callback_periods: int = 0, backends: Optional[List[miniaudio.Backend]] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
> An audio device provided by miniaudio, for audio playback.

> *field* ``backend``
> > The audio back-end that is used to play audio through the system.

> *field* ``buffersize_msec``
> > The length of the audio buffer to hold in this device, in milliseconds.

> *field* ``callback_generator``
> > An optional callback generator to get audio data from. The audio data is provided by this
callback generator. The generator gets sent the required number of frames and should yield the
sample data as raw ``bytes``, a ``memoryview``, an ``array.array``, or as a numpy array with shape
``(numframes, numchannels)``. The generator should already be started before setting it here.

> *field* ``format``
> > The sample format to play audio at.

> *field* ``nchannels``
> > The number of audio channels to play audio at.

> *field* ``running``
> > Whether audio is currently being played.

> *field* ``sample_rate``
> > The number of samples to play per second.

> *field* ``sample_width``
> > The width of the samples to play audio at, in bytes.

> *method* ``close (self) ``
> > Halt playback or capture and close down the device. If you use the device as a context manager,
it will be closed automatically.
Expand All @@ -466,6 +598,30 @@ The generator should already be started before passing it in.
``SoundFileInfo (self, name: str, file_format: miniaudio.FileFormat, nchannels: int, sample_rate: int, sample_format: miniaudio.SampleFormat, duration: float, num_frames: int) ``
> Contains various properties of an audio file.

> *field* ``duration``
> > The duration of the audio in this file if played back at normal rate, in seconds (as ``float``).

> *field* ``name``
> > The path to the file.

> *field* ``nchannels``
> > The number of audio channels that this file contains.

> *field* ``num_frames``
> > The total number of frames contained in this file.

> *field* ``sample_format``
> > The sample format contained in this file, as a ``SampleFormat`` enum.

> *field* ``sample_format_name``
> > A human-readable name for the ``sample_format`` field, as a string.

> *field* ``sample_rate``
> > The number of samples that should be played per second to play this file back at normal rate.

> *field* ``sample_width``
> > The width of the samples contained in this file, in bytes.


*class* ``StreamableSource``

Expand All @@ -489,6 +645,33 @@ give the file type to a decoder upfront. You can ignore this method then.
``WavFileReadStream (self, pcm_sample_gen: Generator[Union[bytes, array.array], int, NoneType], sample_rate: int, nchannels: int, output_format: miniaudio.SampleFormat, max_frames: int = 0) ``
> An IO stream that reads as a .wav file, and which gets its pcm samples from the provided producer

> *field* ``buffered``
> > The current samples in the buffer, as the stream is streaming, as raw ``bytes``.

> *field* ``bytes_done``
> > The number of bytes that have been streamed so far.

> *field* ``format``
> > The sample format provided by this stream.

> *field* ``max_bytes``
> > The maximum size of the buffer kept for this stream, in bytes.

> *field* ``max_frames``
> > The maximum number of frames to keep in the buffer for this stream.

> *field* ``nchannels``
> > The number of channels provided by this stream.

> *field* ``sample_gen``
> > A generator used to provide samples to this stream.

> *field* ``sample_rate``
> > The sample rate provided by this stream.

> *field* ``sample_width``
> > The width of the samples provided by this stream.

> *method* ``close (self) ``
> > Close the file

Expand Down