custom audio objects document ambiguity and more info

[xnor]

The docs here are relatively vague about creating your own audio objects:

https://www.pjrc.com/teensy/td_libs_AudioNewObjects.html

First off, this document doesn't indicate any return values for the methods it highlights, is there a better set of annotated methods?
I did find the source in the github repo, https://github.com/PaulStoffregen/cores/blob/master/teensy3/AudioStream.h but there is very little commenting. I find that this is the case for most of the libraries, it is hard to find documentation, is there a definitive location for this that I'm missing? I'd recommend at least adding a link to the header file in the document about creating your own objects.

Second:
For input you have to provide the number of channels and an "array of audio block pointers used for the inputs" in the constructor.. but then later the doc indicates 2 functions "receiveReadOnly(channel);" and "receiveWritable(channel);"
"Receive a block of incoming audio from an input channel..."
So this is in addition to passing my array of input buffers to the AudioStream constructor? Does one normally just assign back into the array that you passed to the constructor? I assume I need to call release on any block I get from these receive methods even if I'm storing their return value in an instance variable [iqueue]?

Third:
I see that allocate [and the receive methods above] can return null. Besides memory concerns, is there any reason not to just have audio_buffer_t objects [not pointers] in my class and avoid allocate/release?

Finally:
I'm using floating point for my audio computation. Do you [Paul] have any code [teensy 3.6] to efficiently convert between an array of floats from -1..1 and to an array of int16_t [INT16_MIN..INT16_MAX] ideally with the ability to deal with interleaving/de-interleaving?

Thanks,
Alex

 

[PaulStoffregen]

but there is very little commenting. I find that this is the case for most of the libraries, it is hard to find documentation, is there a definitive location for this that I'm missing?

That's all the documentation which currently exists. Yeah, it'd probably be nice if more were written, but you're just going to have to make do. Unless someone volunteers, better dev documentation is unlikely anytime soon.

The "normal" path is to copy and modify some of the existing objects. If you're doing only pure math, it's pretty simple. If you're doing I/O that's synchronous to the sample rate, the existing input and output objects are also a good starting point. If you're going to do something like the USB I/O, well, that's really tough no matter what you do!

For input you have to provide the number of channels and an "array of audio block pointers used for the inputs" in the constructor.. but then later the doc indicates 2 functions "receiveReadOnly(channel);" and "receiveWritable(channel);"
"Receive a block of incoming audio from an input channel..."
So this is in addition to passing my array of input buffers to the AudioStream constructor?

Yes, that array of pointers is in addition to the audio blocks, just like it says. It actually serves a completely different purpose.

Does one normally just assign back into the array that you passed to the constructor?

No. You just give that small array to the constructor and then forget about it. Never touch it again. Don't confuse it with the arrays for the actual audio blocks.

Sorry, I don't have time for a lengthy explanation. You're going to have to just trust me on this one. Or dig into the AudioStream.cpp code, but to put this a bit bluntly, if you're already unhappy with the lack of documentation, save yourself the trouble now and just accept this is simply part of how the system works.

I assume I need to call release on any block I get from these receive methods even if I'm storing their return value in an instance variable [iqueue]?

Yes, you need to release any block you receive or allocate. But you're not required to do so within the same update(). Obviously that is the most common scenario, but if you want to implement delay or other effects by holding on to blocks, your certainly can.

After you release a block, of course you shouldn't access it. Continuing to store a pointer after release is just asking for trouble....

I see that allocate [and the receive methods above] can return null. Besides memory concerns, is there any reason not to just have audio_buffer_t objects [not pointers] in my class and avoid allocate/release?

Normally this isn't done. You can do pretty much whatever you like within your own object. But you must not transmit blocks to the rest of the system which you didn't obtain in the normal way with allocate or receive. Likewise, calling release() with a pointer to a block that didn't come from allocate or receive can be expected to do something bad.

 

[xnor]

Hey Paul, thanks for the quick response. Sorry if I was a bit negative with my tone last night, was just kinda frustrated and it was the end of a long day.. Maybe I'll add some inline documentation and send you a pull request on github.

Its good to know that I shouldn't touch the queue that I pass to the constructor and that I shouldn't transmit anything I don't get via receive/allocate. I think I now have everything I need to move forward!

Thanks,
Alex