Documentation for "Callback Streams" and "Blocking Read/Write Streams" is unclear.

[amosdevstudio]

By reading the docs it is unclear to me how Callback functions work, when they are called and all the parameters do exactly . I think I have figured it out from the examples and the source code, but i think this project has a lot of lost potential just because these more "advanced" features don't have much documentation. I would be willing to help write some of the documentation if necessary, although i first want to make sure I understand these features correctly.

[mgeier]

Thanks for bringing this up!

There is hardly any documentation for "blocking" streams: https://python-sounddevice.readthedocs.io/en/0.5.1/usage.html#blocking-read-write-streams
That's because I have never used them and I don't even know whether the blocking behavior plays nicely with Python.

If somebody has used them, I'd be interested in hearing about it.

figured it out from the examples

Yeah, I consider the examples an important part of the documentation.

But I'm open for improvements in the prose part of the documentation as well!

how Callback functions work, when they are called

Yeah, this could definitely be improved.

For example, I think it is not explicitly mentioned that the callback function runs in an OS-thread created by the PortAudio library.

... all the parameters do exactly

This is described in excruciating detail, did you not find it?

The description can for sure be improved, though.

I would be willing to help write some of the documentation

Yes please, that would be great!

[amosdevstudio]

Thanks for your politeness!
I'm sorry if I was not clear, the issue in my opinion is not with the API documentation, but with the structure of the overall docs, which i personally find hard to follow (although this is just an opinion, obviously). The reason for this is that I think a lot of pieces on the API part of the docs (which I find well written) would be better suited in the "usage" part of the docs. In my opinion, the "usage" part should give the reader a general sense of what the functions do and how they work, much like a tutorial, while the API part should be for the technical part of the docs and for additional features one might want.
This difference is mostly for people who don't really know all that much about audio and how PortAudio works under the hood. For instance, not everyone might know that audio is divided into blocks, and if you don't know it, you have to kind of infer it from the blocksize parameter. This is not bad per se, but I think a more "Arch Wiki" approach might help even complete beginners to understand audio and this library.

There is hardly any documentation for "blocking" streams

I personally haven't used them (and honestly I don't quite understand how they work), but I am willing to help, both on the docs side and the implementation side!

Yeah, I consider the examples an important part of the documentation.

I also consider them to be very important, but i think they should be accessed as a supplement, don't you think? I would like to hear your opinion on this.

For example, I think it is not explicitly mentioned that the callback function runs in an OS-thread created by the PortAudio library.

From what i saw, it is not. Although it is mentioned in at least one of the examples.

This is described in excruciating detail, did you not find it?

Yes, sorry I just didn't explain myself correctly :P

Yes please, that would be great!

In order to contribute, should I just submit a PR referencing this issue and refining it if it is not clear enough / has incorrect info? Are you willing to accept PRs on this issue?

[mgeier]

Are you willing to accept PRs on this issue?

Yes, definitely!