Skip to content

Commit 5933239

Browse files
irmenirmen
committed
release 1.38.
removed problematic unit test fragment. fixed mypy typing errors. updated apidocs in readme.
1 parent 6c5ba54 commit 5933239

File tree

4 files changed

+375
-15
lines changed

4 files changed

+375
-15
lines changed

‎README.md‎

Lines changed: 361 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,4 +102,364 @@ with miniaudio.PlaybackDevice(output_format=miniaudio.SampleFormat.SIGNED16,
102102
## API
103103

104104

105-
TODO: update the API doc
105+
*enum class* ``Backend``
106+
names: ``WASAPI`` ``DSOUND`` ``WINMM`` ``COREAUDIO`` ``SNDIO`` ``AUDIO4`` ``OSS`` ``PULSEAUDIO`` ``ALSA`` ``JACK`` ``AAUDIO`` ``OPENSL`` ``WEBAUDIO`` ``CUSTOM`` ``NULL``
107+
> Operating system audio backend to use (only a subset will be available)
108+
109+
110+
*enum class* ``ChannelMixMode``
111+
names: ``RECTANGULAR`` ``SIMPLE`` ``CUSTOMWEIGHTS``
112+
> How to mix channels when converting
113+
114+
115+
*enum class* ``DeviceType``
116+
names: ``PLAYBACK`` ``CAPTURE`` ``DUPLEX``
117+
> Type of audio device
118+
119+
120+
*enum class* ``DitherMode``
121+
names: ``NONE`` ``RECTANGLE`` ``TRIANGLE``
122+
> How to dither when converting
123+
124+
125+
*enum class* ``FileFormat``
126+
names: ``UNKNOWN`` ``WAV`` ``FLAC`` ``VORBIS`` ``MP3``
127+
> Audio file format
128+
129+
130+
*enum class* ``SampleFormat``
131+
names: ``UNKNOWN`` ``UNSIGNED8`` ``SIGNED16`` ``SIGNED24`` ``SIGNED32`` ``FLOAT32``
132+
> Sample format in memory
133+
134+
135+
*enum class* ``SeekOrigin``
136+
names: ``START`` ``CURRENT``
137+
> How to seek() in a source
138+
139+
140+
*enum class* ``ThreadPriority``
141+
names: ``IDLE`` ``LOWEST`` ``LOW`` ``NORMAL`` ``HIGH`` ``HIGHEST`` ``REALTIME``
142+
> The priority of the worker thread (default=HIGHEST)
143+
144+
145+
*function* ``convert_frames (from_fmt: miniaudio.SampleFormat, from_numchannels: int, from_samplerate: int, sourcedata: bytes, to_fmt: miniaudio.SampleFormat, to_numchannels: int, to_samplerate: int) -> bytearray``
146+
> Convert audio frames in source sample format with a certain number of channels, to another sample
147+
format and possibly down/upmixing the number of channels as well.
148+
149+
150+
*function* ``convert_sample_format (from_fmt: miniaudio.SampleFormat, sourcedata: bytes, to_fmt: miniaudio.SampleFormat, dither: miniaudio.DitherMode = <DitherMode.NONE: 0>) -> bytearray``
151+
> Convert a raw buffer of pcm samples to another sample format. The result is returned as another
152+
raw pcm sample buffer
153+
154+
155+
*function* ``decode (data: bytes, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, dither: miniaudio.DitherMode = <DitherMode.NONE: 0>) -> miniaudio.DecodedSoundFile``
156+
> Convenience function to decode any supported audio file in memory to raw PCM samples in your
157+
chosen format.
158+
159+
160+
*function* ``decode_file (filename: str, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, dither: miniaudio.DitherMode = <DitherMode.NONE: 0>) -> miniaudio.DecodedSoundFile``
161+
> Convenience function to decode any supported audio file to raw PCM samples in your chosen format.
162+
163+
164+
*function* ``flac_get_file_info (filename: str) -> miniaudio.SoundFileInfo``
165+
> Fetch some information about the audio file (flac format).
166+
167+
168+
*function* ``flac_get_info (data: bytes) -> miniaudio.SoundFileInfo``
169+
> Fetch some information about the audio data (flac format).
170+
171+
172+
*function* ``flac_read_f32 (data: bytes) -> miniaudio.DecodedSoundFile``
173+
> Reads and decodes the whole flac audio file. Resulting sample format is 32 bits float.
174+
175+
176+
*function* ``flac_read_file_f32 (filename: str) -> miniaudio.DecodedSoundFile``
177+
> Reads and decodes the whole flac audio file. Resulting sample format is 32 bits float.
178+
179+
180+
*function* ``flac_read_file_s16 (filename: str) -> miniaudio.DecodedSoundFile``
181+
> Reads and decodes the whole flac audio file. Resulting sample format is 16 bits signed integer.
182+
183+
184+
*function* ``flac_read_file_s32 (filename: str) -> miniaudio.DecodedSoundFile``
185+
> Reads and decodes the whole flac audio file. Resulting sample format is 32 bits signed integer.
186+
187+
188+
*function* ``flac_read_s16 (data: bytes) -> miniaudio.DecodedSoundFile``
189+
> Reads and decodes the whole flac audio data. Resulting sample format is 16 bits signed integer.
190+
191+
192+
*function* ``flac_read_s32 (data: bytes) -> miniaudio.DecodedSoundFile``
193+
> Reads and decodes the whole flac audio data. Resulting sample format is 32 bits signed integer.
194+
195+
196+
*function* ``flac_stream_file (filename: str, frames_to_read: int = 1024, seek_frame: int = 0) -> Generator[array.array, NoneType, NoneType]``
197+
> Streams the flac audio file as interleaved 16 bit signed integer sample arrays segments. This uses
198+
a fixed chunk size and cannot be used as a generic miniaudio decoder input stream. Consider using
199+
stream_file() instead.
200+
201+
202+
*function* ``get_enabled_backends () -> Set[miniaudio.Backend]``
203+
> Returns the set of available backends by the compilation environment for the underlying miniaudio
204+
C library
205+
206+
207+
*function* ``get_file_info (filename: str) -> miniaudio.SoundFileInfo``
208+
> Fetch some information about the audio file.
209+
210+
211+
*function* ``is_backend_enabled (backend: miniaudio.Backend) -> bool``
212+
> Determines whether or not the given backend is available by the compilation environment for the
213+
underlying miniaudio C library
214+
215+
216+
*function* ``is_loopback_supported (backend: miniaudio.Backend) -> bool``
217+
> Determines whether or not loopback mode is support by a backend.
218+
219+
220+
*function* ``lib_version () -> str``
221+
> Returns the version string of the underlying miniaudio C library
222+
223+
224+
*function* ``mp3_get_file_info (filename: str) -> miniaudio.SoundFileInfo``
225+
> Fetch some information about the audio file (mp3 format).
226+
227+
228+
*function* ``mp3_get_info (data: bytes) -> miniaudio.SoundFileInfo``
229+
> Fetch some information about the audio data (mp3 format).
230+
231+
232+
*function* ``mp3_read_f32 (data: bytes) -> miniaudio.DecodedSoundFile``
233+
> Reads and decodes the whole mp3 audio data. Resulting sample format is 32 bits float.
234+
235+
236+
*function* ``mp3_read_file_f32 (filename: str) -> miniaudio.DecodedSoundFile``
237+
> Reads and decodes the whole mp3 audio file. Resulting sample format is 32 bits float.
238+
239+
240+
*function* ``mp3_read_file_s16 (filename: str) -> miniaudio.DecodedSoundFile``
241+
> Reads and decodes the whole mp3 audio file. Resulting sample format is 16 bits signed integer.
242+
243+
244+
*function* ``mp3_read_s16 (data: bytes) -> miniaudio.DecodedSoundFile``
245+
> Reads and decodes the whole mp3 audio data. Resulting sample format is 16 bits signed integer.
246+
247+
248+
*function* ``mp3_stream_file (filename: str, frames_to_read: int = 1024, seek_frame: int = 0) -> Generator[array.array, NoneType, NoneType]``
249+
> Streams the mp3 audio file as interleaved 16 bit signed integer sample arrays segments. This uses
250+
a fixed chunk size and cannot be used as a generic miniaudio decoder input stream. Consider using
251+
stream_file() instead.
252+
253+
254+
*function* ``read_file (filename: str, convert_to_16bit: bool = False) -> miniaudio.DecodedSoundFile``
255+
> Reads and decodes the whole audio file. Miniaudio will attempt to return the sound data in exactly
256+
the same format as in the file. Unless you set convert_convert_to_16bit to True, then the result is
257+
always a 16 bit sample format.
258+
259+
260+
*function* ``stream_any (source: miniaudio.StreamableSource, source_format: miniaudio.FileFormat = <FileFormat.UNKNOWN: 0>, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, frames_to_read: int = 1024, dither: miniaudio.DitherMode = <DitherMode.NONE: 0>, seek_frame: int = 0) -> Generator[array.array, int, NoneType]``
261+
> Convenience function that returns a generator to decode and stream any source of encoded audio
262+
data (such as a network stream). Stream result is chunks of raw PCM samples in the chosen format. If
263+
you send() a number into the generator rather than just using next() on it, you'll get that given
264+
number of frames, instead of the default configured amount. This is particularly useful to plug this
265+
stream into an audio device callback that wants a variable number of frames per call.
266+
267+
268+
*function* ``stream_file (filename: str, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, frames_to_read: int = 1024, dither: miniaudio.DitherMode = <DitherMode.NONE: 0>, seek_frame: int = 0) -> Generator[array.array, int, NoneType]``
269+
> Convenience generator function to decode and stream any supported audio file as chunks of raw PCM
270+
samples in the chosen format. If you send() a number into the generator rather than just using
271+
next() on it, you'll get that given number of frames, instead of the default configured amount. This
272+
is particularly useful to plug this stream into an audio device callback that wants a variable
273+
number of frames per call.
274+
275+
276+
*function* ``stream_memory (data: bytes, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, frames_to_read: int = 1024, dither: miniaudio.DitherMode = <DitherMode.NONE: 0>) -> Generator[array.array, int, NoneType]``
277+
> Convenience generator function to decode and stream any supported audio file in memory as chunks
278+
of raw PCM samples in the chosen format. If you send() a number into the generator rather than just
279+
using next() on it, you'll get that given number of frames, instead of the default configured
280+
amount. This is particularly useful to plug this stream into an audio device callback that wants a
281+
variable number of frames per call.
282+
283+
284+
*function* ``vorbis_get_file_info (filename: str) -> miniaudio.SoundFileInfo``
285+
> Fetch some information about the audio file (vorbis format).
286+
287+
288+
*function* ``vorbis_get_info (data: bytes) -> miniaudio.SoundFileInfo``
289+
> Fetch some information about the audio data (vorbis format).
290+
291+
292+
*function* ``vorbis_read (data: bytes) -> miniaudio.DecodedSoundFile``
293+
> Reads and decodes the whole vorbis audio data. Resulting sample format is 16 bits signed integer.
294+
295+
296+
*function* ``vorbis_read_file (filename: str) -> miniaudio.DecodedSoundFile``
297+
> Reads and decodes the whole vorbis audio file. Resulting sample format is 16 bits signed integer.
298+
299+
300+
*function* ``vorbis_stream_file (filename: str, seek_frame: int = 0) -> Generator[array.array, NoneType, NoneType]``
301+
> Streams the ogg vorbis audio file as interleaved 16 bit signed integer sample arrays segments.
302+
This uses a variable unconfigurable chunk size and cannot be used as a generic miniaudio decoder
303+
input stream. Consider using stream_file() instead.
304+
305+
306+
*function* ``wav_get_file_info (filename: str) -> miniaudio.SoundFileInfo``
307+
> Fetch some information about the audio file (wav format).
308+
309+
310+
*function* ``wav_get_info (data: bytes) -> miniaudio.SoundFileInfo``
311+
> Fetch some information about the audio data (wav format).
312+
313+
314+
*function* ``wav_read_f32 (data: bytes) -> miniaudio.DecodedSoundFile``
315+
> Reads and decodes the whole wav audio data. Resulting sample format is 32 bits float.
316+
317+
318+
*function* ``wav_read_file_f32 (filename: str) -> miniaudio.DecodedSoundFile``
319+
> Reads and decodes the whole wav audio file. Resulting sample format is 32 bits float.
320+
321+
322+
*function* ``wav_read_file_s16 (filename: str) -> miniaudio.DecodedSoundFile``
323+
> Reads and decodes the whole wav audio file. Resulting sample format is 16 bits signed integer.
324+
325+
326+
*function* ``wav_read_file_s32 (filename: str) -> miniaudio.DecodedSoundFile``
327+
> Reads and decodes the whole wav audio file. Resulting sample format is 32 bits signed integer.
328+
329+
330+
*function* ``wav_read_s16 (data: bytes) -> miniaudio.DecodedSoundFile``
331+
> Reads and decodes the whole wav audio data. Resulting sample format is 16 bits signed integer.
332+
333+
334+
*function* ``wav_read_s32 (data: bytes) -> miniaudio.DecodedSoundFile``
335+
> Reads and decodes the whole wav audio data. Resulting sample format is 32 bits signed integer.
336+
337+
338+
*function* ``wav_stream_file (filename: str, frames_to_read: int = 1024, seek_frame: int = 0) -> Generator[array.array, NoneType, NoneType]``
339+
> Streams the WAV audio file as interleaved 16 bit signed integer sample arrays segments. This uses
340+
a fixed chunk size and cannot be used as a generic miniaudio decoder input stream. Consider using
341+
stream_file() instead.
342+
343+
344+
*function* ``wav_write_file (filename: str, sound: miniaudio.DecodedSoundFile) ``
345+
> Writes the pcm sound to a WAV file
346+
347+
348+
*class* ``CaptureDevice``
349+
350+
``CaptureDevice (self, input_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Union[_cffi_backend._CDataBase, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
351+
> An audio device provided by miniaudio, for audio capture (recording).
352+
353+
> *method* ``close (self) ``
354+
> > Halt playback or capture and close down the device. If you use the device as a context manager,
355+
it will be closed automatically.
356+
357+
> *method* ``start (self, callback_generator: Generator[NoneType, Union[bytes, array.array], NoneType], stop_callback: Union[Callable, NoneType] = None) ``
358+
> > Start the audio device: capture (recording) begins. The recorded audio data is sent to the given
359+
callback generator as raw bytes. (it should already be started before)
360+
361+
> *method* ``stop (self) ``
362+
> > Halt playback or capture.
363+
364+
365+
*class* ``DecodeError``
366+
367+
``DecodeError (self, /, *args, **kwargs)``
368+
> When something went wrong during decoding an audio file.
369+
370+
371+
*class* ``DecodedSoundFile``
372+
373+
``DecodedSoundFile (self, name: str, nchannels: int, sample_rate: int, sample_format: miniaudio.SampleFormat, samples: array.array) ``
374+
> Contains various properties and also the PCM frames of a fully decoded audio file.
375+
376+
377+
*class* ``Devices``
378+
379+
``Devices (self, backends: Union[List[miniaudio.Backend], NoneType] = None) ``
380+
> Query the audio playback and record devices that miniaudio provides
381+
382+
> *method* ``get_captures (self) -> List[Dict[str, Any]]``
383+
> > Get a list of capture devices and some details about them
384+
385+
> *method* ``get_playbacks (self) -> List[Dict[str, Any]]``
386+
> > Get a list of playback devices and some details about them
387+
388+
389+
*class* ``DuplexStream``
390+
391+
``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: Union[_cffi_backend._CDataBase, NoneType] = None, capture_device_id: Union[_cffi_backend._CDataBase, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
392+
> Joins a capture device and a playback device.
393+
394+
> *method* ``close (self) ``
395+
> > Halt playback or capture and close down the device. If you use the device as a context manager,
396+
it will be closed automatically.
397+
398+
> *method* ``start (self, callback_generator: Generator[Union[bytes, array.array], Union[bytes, array.array], NoneType], stop_callback: Union[Callable, NoneType] = None) ``
399+
> > Start the audio device: playback and capture begin. The audio data for playback is provided by
400+
the given callback generator, which is sent the recorded audio data at the same time. (it should
401+
already be started before passing it in)
402+
403+
> *method* ``stop (self) ``
404+
> > Halt playback or capture.
405+
406+
407+
*class* ``IceCastClient``
408+
409+
``IceCastClient (self, url: str, block_size: int = 16384, update_stream_title: Callable[[ForwardRef('IceCastClient'), str], NoneType] = None) ``
410+
> A simple client for IceCast audio streams as miniaudio streamable source. If the stream has Icy
411+
Meta Data, the stream_title attribute will be updated with the actual title taken from the meta
412+
data. You can also provide a callback to be called when a new stream title is available.
413+
414+
415+
*class* ``MiniaudioError``
416+
417+
``MiniaudioError (self, /, *args, **kwargs)``
418+
> When a miniaudio specific error occurs.
419+
420+
421+
*class* ``PlaybackDevice``
422+
423+
``PlaybackDevice (self, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Union[_cffi_backend._CDataBase, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
424+
> An audio device provided by miniaudio, for audio playback.
425+
426+
> *method* ``close (self) ``
427+
> > Halt playback or capture and close down the device. If you use the device as a context manager,
428+
it will be closed automatically.
429+
430+
> *method* ``start (self, callback_generator: Generator[Union[bytes, array.array], int, NoneType], stop_callback: Union[Callable, NoneType] = None) ``
431+
> > Start the audio device: playback begins. The audio data is provided by the given callback
432+
generator. The generator gets sent the required number of frames and should yield the sample data as
433+
raw bytes, a memoryview, an array.array, or as a numpy array with shape (numframes, numchannels).
434+
The generator should already be started before passing it in.
435+
436+
> *method* ``stop (self) ``
437+
> > Halt playback or capture.
438+
439+
440+
*class* ``SoundFileInfo``
441+
442+
``SoundFileInfo (self, name: str, file_format: miniaudio.FileFormat, nchannels: int, sample_rate: int, sample_format: miniaudio.SampleFormat, duration: float, num_frames: int) ``
443+
> Contains various properties of an audio file.
444+
445+
446+
*class* ``StreamableSource``
447+
448+
``StreamableSource (self, /, *args, **kwargs)``
449+
> Base class for streams of audio data bytes. Can be used as a contextmanager, to properly call
450+
close().
451+
452+
453+
*class* ``WavFileReadStream``
454+
455+
``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) ``
456+
> An IO stream that reads as a .wav file, and which gets its pcm samples from the provided producer
457+
458+
> *method* ``close (self) ``
459+
> > Close the file
460+
461+
> *method* ``read (self, amount: int = 9223372036854775807) -> Union[bytes, NoneType]``
462+
> > Read up to the given amount of bytes from the file.
463+
464+
465+

‎build_ffi_module.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -523,6 +523,7 @@
523523
{
524524
ma_device_id id;
525525
char name[256];
526+
ma_bool32 isDefault;
526527
ma_uint32 formatCount;
527528
ma_format formats[ma_format_count];
528529
ma_uint32 minChannels;

0 commit comments

Comments
 (0)