Incorrect stereo configuration when writing file causes unhelpful error message (especially if not using NumPy)

[mcclure]

Imagine the array configuration of the input to SoundFile.write is incorrect. For example, I triggered this by passing in interleaved stereo data where SoundFile.write expects an array of 2-element arrays. The error message was an exception thrown from two layers deep inside SoundFile, reading "Invalid shape: (960,)". Later, after understanding this was incorrect but while still a little confused, I tried. This got the error "Invalid shape: (2, 480)".

There are a few problems with this error message which make it less helpful than it could be.

1. It is not clear that this is related to an function parameter, or if it is, which parameter. When I first saw this it appeared to be an internal error in the library. The documentation very clearly explains the correct format, but I did not go looking at the documentation because I thought it was a library error and instead wound up reading the source. A message with less information like "parameter 1 incorrectly formatted" would have maybe been more helpful for this reason.
2. There are three different conditions that can trigger this single error, but which one is not indicated.
3. Most importantly, the error is described in terms of numpy semantics instead of library semantics. The error is that the dimension of the input array does not match the current (mono, stereo) value. But instead of talking about mono vs stereo, it gives the numpy multidimensional array shape. It may be a numpy user would immediately know what "shape (960,)" means, but I am not using numpy, so it was not obvious to me what "shape" referred to.

My expected behavior would be that this would read like "Stereo data expected (got data with shape: (960,)" or "Mono data expected (got data with shape: (480,2)".

Exact error message

Repro

I have a repro but it is not very convenient. You can check out https://github.com/mcclure/analogue-core-template-amaranth and check out revision 1e31ea635bdb880c411a79dedf107c51b9be16f0 . You will want to install "pdm" with pip, and probably want to edit src/fpga/amaranth_core/pyproject.toml to include "soundfile" instead of "pysoundfile", then you can run with (cd src/fpga/amaranth_core && python.exe -m pdm install && python.exe -m pdm capture_wav). It will take some time to complete.

The part that uses python-soundfile is here.

[bastibe]

Thank you for the bug report. I agree that error messages could be improved.

Would you like to contribute a pull request with better error messages?