Skip to content

Commit 088b5b1

Browse files
evaherradaevaherrada
committed
Added inline pyi to audiocore
1 parent e96235d commit 088b5b1

File tree

2 files changed

+104
-115
lines changed

2 files changed

+104
-115
lines changed

‎shared-bindings/audiocore/RawSample.c

Lines changed: 55 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -35,45 +35,45 @@
3535
#include "shared-bindings/audiocore/RawSample.h"
3636
#include "supervisor/shared/translate.h"
3737

38-
//| .. currentmodule:: audiocore
39-
//|
40-
//| :class:`RawSample` -- A raw audio sample buffer
41-
//| ========================================================
42-
//|
43-
//| An in-memory sound sample
44-
//|
45-
//| .. class:: RawSample(buffer, *, channel_count=1, sample_rate=8000)
46-
//|
47-
//| Create a RawSample based on the given buffer of signed values. If channel_count is more than
48-
//| 1 then each channel's samples should alternate. In other words, for a two channel buffer, the
49-
//| first sample will be for channel 1, the second sample will be for channel two, the third for
50-
//| channel 1 and so on.
51-
//|
52-
//| :param array.array buffer: An `array.array` with samples
53-
//| :param int channel_count: The number of channels in the buffer
54-
//| :param int sample_rate: The desired playback sample rate
55-
//|
56-
//| Simple 8ksps 440 Hz sin wave::
57-
//|
58-
//| import audiocore
59-
//| import audioio
60-
//| import board
61-
//| import array
62-
//| import time
63-
//| import math
64-
//|
65-
//| # Generate one period of sine wav.
66-
//| length = 8000 // 440
67-
//| sine_wave = array.array("h", [0] * length)
68-
//| for i in range(length):
69-
//| sine_wave[i] = int(math.sin(math.pi * 2 * i / 18) * (2 ** 15))
70-
//|
71-
//| dac = audioio.AudioOut(board.SPEAKER)
72-
//| sine_wave = audiocore.RawSample(sine_wave)
73-
//| dac.play(sine_wave, loop=True)
74-
//| time.sleep(1)
75-
//| dac.stop()
76-
//|
38+
//|class RawSample:
39+
//| """.. currentmodule:: audiocore
40+
//|
41+
//| :class:`RawSample` -- A raw audio sample buffer
42+
//| ========================================================
43+
//|
44+
//| An in-memory sound sample"""
45+
//|
46+
//| def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000):
47+
//| """Create a RawSample based on the given buffer of signed values. If channel_count is more than
48+
//| 1 then each channel's samples should alternate. In other words, for a two channel buffer, the
49+
//| first sample will be for channel 1, the second sample will be for channel two, the third for
50+
//| channel 1 and so on.
51+
//|
52+
//| :param array.array buffer: An `array.array` with samples
53+
//| :param int channel_count: The number of channels in the buffer
54+
//| :param int sample_rate: The desired playback sample rate
55+
//|
56+
//| Simple 8ksps 440 Hz sin wave::
57+
//|
58+
//| import audiocore
59+
//| import audioio
60+
//| import board
61+
//| import array
62+
//| import time
63+
//| import math
64+
//|
65+
//| # Generate one period of sine wav.
66+
//| length = 8000 // 440
67+
//| sine_wave = array.array("h", [0] * length)
68+
//| for i in range(length):
69+
//| sine_wave[i] = int(math.sin(math.pi * 2 * i / 18) * (2 ** 15))
70+
//|
71+
//| dac = audioio.AudioOut(board.SPEAKER)
72+
//| sine_wave = audiocore.RawSample(sine_wave)
73+
//| dac.play(sine_wave, loop=True)
74+
//| time.sleep(1)
75+
//| dac.stop()"""
76+
//| ...
7777
STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
7878
enum { ARG_buffer, ARG_channel_count, ARG_sample_rate };
7979
static const mp_arg_t allowed_args[] = {
@@ -105,10 +105,9 @@ STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_a
105105
return MP_OBJ_FROM_PTR(self);
106106
}
107107

108-
//| .. method:: deinit()
109-
//|
110-
//| Deinitialises the AudioOut and releases any hardware resources for reuse.
111-
//|
108+
//| def deinit(self, ) -> Any:
109+
//| """Deinitialises the AudioOut and releases any hardware resources for reuse."""
110+
//| ...
112111
STATIC mp_obj_t audioio_rawsample_deinit(mp_obj_t self_in) {
113112
audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in);
114113
common_hal_audioio_rawsample_deinit(self);
@@ -122,31 +121,28 @@ STATIC void check_for_deinit(audioio_rawsample_obj_t *self) {
122121
}
123122
}
124123

125-
//| .. method:: __enter__()
126-
//|
127-
//| No-op used by Context Managers.
128-
//|
124+
//| def __enter__(self, ) -> Any:
125+
//| """No-op used by Context Managers."""
126+
//| ...
129127
// Provided by context manager helper.
130128

131-
//| .. method:: __exit__()
132-
//|
133-
//| Automatically deinitializes the hardware when exiting a context. See
134-
//| :ref:`lifetime-and-contextmanagers` for more info.
135-
//|
129+
//| def __exit__(self, ) -> Any:
130+
//| """Automatically deinitializes the hardware when exiting a context. See
131+
//| :ref:`lifetime-and-contextmanagers` for more info."""
132+
//| ...
136133
STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *args) {
137134
(void)n_args;
138135
common_hal_audioio_rawsample_deinit(args[0]);
139136
return mp_const_none;
140137
}
141138
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_rawsample___exit___obj, 4, 4, audioio_rawsample_obj___exit__);
142139

143-
//| .. attribute:: sample_rate
144-
//|
145-
//| 32 bit value that dictates how quickly samples are played in Hertz (cycles per second).
146-
//| When the sample is looped, this can change the pitch output without changing the underlying
147-
//| sample. This will not change the sample rate of any active playback. Call ``play`` again to
148-
//| change it.
149-
//|
140+
//| sample_rate: Any =
141+
//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second).
142+
//| When the sample is looped, this can change the pitch output without changing the underlying
143+
//| sample. This will not change the sample rate of any active playback. Call ``play`` again to
144+
//| change it."""
145+
//| ...
150146
STATIC mp_obj_t audioio_rawsample_obj_get_sample_rate(mp_obj_t self_in) {
151147
audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in);
152148
check_for_deinit(self);

‎shared-bindings/audiocore/WaveFile.c

Lines changed: 49 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -33,44 +33,43 @@
3333
#include "shared-bindings/util.h"
3434
#include "supervisor/shared/translate.h"
3535

36-
//| .. currentmodule:: audiocore
36+
//|class WaveFile:
37+
//| """.. currentmodule:: audiocore
3738
//|
38-
//| :class:`WaveFile` -- Load a wave file for audio playback
39-
//| ========================================================
39+
//| :class:`WaveFile` -- Load a wave file for audio playback
40+
//| ========================================================
4041
//|
41-
//| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must
42-
//| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating
43-
//| an internal buffer.
42+
//| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must
43+
//| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating
44+
//| an internal buffer."""
45+
//| def __init__(self, file: typing.BinaryIO, buffer: bytearray):
46+
//| """Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`.
4447
//|
45-
//| .. class:: WaveFile(file[, buffer])
48+
//| :param typing.BinaryIO file: Already opened wave file
49+
//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally.
4650
//|
47-
//| Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`.
4851
//|
49-
//| :param typing.BinaryIO file: Already opened wave file
50-
//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally.
52+
//| Playing a wave file from flash::
5153
//|
54+
//| import board
55+
//| import audiocore
56+
//| import audioio
57+
//| import digitalio
5258
//|
53-
//| Playing a wave file from flash::
59+
//| # Required for CircuitPlayground Express
60+
//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE)
61+
//| speaker_enable.switch_to_output(value=True)
5462
//|
55-
//| import board
56-
//| import audiocore
57-
//| import audioio
58-
//| import digitalio
59-
//|
60-
//| # Required for CircuitPlayground Express
61-
//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE)
62-
//| speaker_enable.switch_to_output(value=True)
63-
//|
64-
//| data = open("cplay-5.1-16bit-16khz.wav", "rb")
65-
//| wav = audiocore.WaveFile(data)
66-
//| a = audioio.AudioOut(board.A0)
67-
//|
68-
//| print("playing")
69-
//| a.play(wav)
70-
//| while a.playing:
71-
//| pass
72-
//| print("stopped")
63+
//| data = open("cplay-5.1-16bit-16khz.wav", "rb")
64+
//| wav = audiocore.WaveFile(data)
65+
//| a = audioio.AudioOut(board.A0)
7366
//|
67+
//| print("playing")
68+
//| a.play(wav)
69+
//| while a.playing:
70+
//| pass
71+
//| print("stopped")"""
72+
//| ...
7473
STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) {
7574
mp_arg_check_num(n_args, kw_args, 1, 2, false);
7675

@@ -93,10 +92,9 @@ STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_ar
9392
return MP_OBJ_FROM_PTR(self);
9493
}
9594

96-
//| .. method:: deinit()
97-
//|
98-
//| Deinitialises the WaveFile and releases all memory resources for reuse.
99-
//|
95+
//| def deinit(self, ) -> Any:
96+
//| """Deinitialises the WaveFile and releases all memory resources for reuse."""
97+
//| ...
10098
STATIC mp_obj_t audioio_wavefile_deinit(mp_obj_t self_in) {
10199
audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in);
102100
common_hal_audioio_wavefile_deinit(self);
@@ -110,30 +108,27 @@ STATIC void check_for_deinit(audioio_wavefile_obj_t *self) {
110108
}
111109
}
112110

113-
//| .. method:: __enter__()
114-
//|
115-
//| No-op used by Context Managers.
116-
//|
111+
//| def __enter__(self, ) -> Any:
112+
//| """No-op used by Context Managers."""
113+
//| ...
117114
// Provided by context manager helper.
118115

119-
//| .. method:: __exit__()
120-
//|
121-
//| Automatically deinitializes the hardware when exiting a context. See
122-
//| :ref:`lifetime-and-contextmanagers` for more info.
123-
//|
116+
//| def __exit__(self, ) -> Any:
117+
//| """Automatically deinitializes the hardware when exiting a context. See
118+
//| :ref:`lifetime-and-contextmanagers` for more info."""
119+
//| ...
124120
STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *args) {
125121
(void)n_args;
126122
common_hal_audioio_wavefile_deinit(args[0]);
127123
return mp_const_none;
128124
}
129125
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_wavefile___exit___obj, 4, 4, audioio_wavefile_obj___exit__);
130126

131-
//| .. attribute:: sample_rate
132-
//|
133-
//| 32 bit value that dictates how quickly samples are loaded into the DAC
134-
//| in Hertz (cycles per second). When the sample is looped, this can change
135-
//| the pitch output without changing the underlying sample.
136-
//|
127+
//| sample_rate: Any =
128+
//| """32 bit value that dictates how quickly samples are loaded into the DAC
129+
//| in Hertz (cycles per second). When the sample is looped, this can change
130+
//| the pitch output without changing the underlying sample."""
131+
//| ...
137132
STATIC mp_obj_t audioio_wavefile_obj_get_sample_rate(mp_obj_t self_in) {
138133
audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in);
139134
check_for_deinit(self);
@@ -156,10 +151,9 @@ const mp_obj_property_t audioio_wavefile_sample_rate_obj = {
156151
(mp_obj_t)&mp_const_none_obj},
157152
};
158153

159-
//| .. attribute:: bits_per_sample
160-
//|
161-
//| Bits per sample. (read only)
162-
//|
154+
//| bits_per_sample: Any =
155+
//| """Bits per sample. (read only)"""
156+
//| ...
163157
STATIC mp_obj_t audioio_wavefile_obj_get_bits_per_sample(mp_obj_t self_in) {
164158
audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in);
165159
check_for_deinit(self);
@@ -174,10 +168,9 @@ const mp_obj_property_t audioio_wavefile_bits_per_sample_obj = {
174168
(mp_obj_t)&mp_const_none_obj},
175169
};
176170

177-
//| .. attribute:: channel_count
178-
//|
179-
//| Number of audio channels. (read only)
180-
//|
171+
//| channel_count: Any =
172+
//| """Number of audio channels. (read only)"""
173+
//| ...
181174
STATIC mp_obj_t audioio_wavefile_obj_get_channel_count(mp_obj_t self_in) {
182175
audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in);
183176
check_for_deinit(self);

0 commit comments

Comments
 (0)