Several changes, basis for discussion

[mgeier]

WARNING: this pull request is not meant to be merged as is!
It is rather meant as a basis for discussion and a proof-of-concept of some ideas, but for many things improvements are needed.
Documentation is lacking for most of the new features.

In-between new features, there are also a few minor bugfixes which can be cherry-picked if desired.

Some of the commits became obsolete because of following commits.
e.g. the function decode_number() (d72075f) is not needed anymore because the specialized types introduced in d31a484 provide a much better solution to the problem.
With that, most changes from 2833332 became obsolete, too.

If desired, I can provide individual pull requests for certain features (I can also add documentation, where lacking).

[mgeier]

@bastibe: If you want, you can cherry-pick the following commits (in the given order they should apply cleanly):

0d0f47f
2572742
6ff89db
0162248
c2e4612

For the following commits I'll add some documentation and then do a new pull request:

2948783
beb81b7
d8afffd
1d10fdf (do you like the names format_string and subtype_string?

These didn't apply cleanly, I'll also create a new pull request

e35911c (is _snd_strings really the right name?)
c6d1fd1
ebea05b
313d359

These are a little messy, I'll create a new pull request for these:

2833332
0ed878f
d26b657
aa75302
e835cd3
d31a484
ee736ab

And these are garbage:

d72075f
3785edd

[mgeier]

I'd like to put a few names up for discussion ... please tell me if any of them can be improved ...

The components of file types are now described by format, subtype and endian.
format could be misleading, because in libsndfile the combination of the three is called "format".
OTOH, format can also hold all three OR'ed together and it will still work.
An alternative name would be major or major_format but I suspect this name would be less clear.

The name subtype is used in the comments of libsndfile.h, but we could also call it subformat ...? Again, I like the first variant more.
On the website, this is also called encoding ...

I'm also not sure about endian, because correctly, this would be called "endian-ness". But both endianness and endian_ness look strange to me.

The class attributes format_string and subtype_string seem a little verbose, but OTOH it should be quite clear what they mean.
We could also try format_info and subtype_info ...
I called the function to get these strings get_format_info() because libsndfile uses SFC_GET_FORMAT_INFO. However, I think we should not mix *_string and *_info and use only one of them.

The internal name _snd_strings doesn't seem right to me, maybe it should be called _str_types? In libsndfile the values are called SF_STR_* and the variable to sf_set_string() is called str_type.

And there is a little discrepancy between sample_rate and samplerate. Former is used in PySoundFile, latter in libsndfile. I think it would be good to always use samplerate.

I invented a little helper function _avoid_format_types() ... I don't like the name but I couldn't come up with something better.

EDIT:

In 3abdaf1 I changed this to

assert _raise_error_if_format_type(channels)

... I'm not sure if that's better ...

[mgeier]

Regarding 2572742: I just realized that 'rw' isn't allowed in Python. I guess it should be replaced by 'r+' (and 'w+' should be disallowed).
See http://docs.python.org/3.3/library/functions.html#open

Probably we should also accept 'rb', 'wb' and 'r+b' for completeness?

Also 'a' and 'a+' should be handled (by positioning the read/write pointer after opening).

And 'x', 't' and 'U' should be disallowed, as I think they don't make sense for libsndfile.

Also, the order of the characters seems to be arbitrary ... so this should be also handled by PySoundFile.

All in all, the situation is much more complicated than I initially thought.

See also #19.

[bastibe]

Here's an idea: How about using the binary modes for raw input/output? That actually makes some kind of sense.

[mgeier]

That's an interesting idea, but I fail to see how this makes sense ... can you please elaborate?

What do you mean by "raw"?
The data type SF_FORMAT_RAW or raw bytes in memory as opposed to wrapped into a np.ndarray?

[mgeier]

OK, I think I now get what you mean with "raw".
You mean the functions sf_read_raw() and sf_write_raw(), right?

I don't think the 'b'-flag is suitable for that.
First, all files handled by libsndfile are binary files, there are no text files among them. Therefore it's confusing why you should open a file without 'b' if it's a normal sound file.
Second, it's the wrong time. The mode is relevant when opening the file, the selection about raw or not raw should happen when calling read() or write().

Another confusing aspect is that the "normal" read/write function use frames, and the raw functions use bytes, therefore I wouldn't recommend putting the functionality into the same function.

I guess it would be better to make new methods read_raw(buffer, bytes) and write_raw(buffer, bytes).

[mgeier]

The functions should probably be called read_bytes() and write_bytes() to avoid confusion with the major type "RAW" which just means header-less.

Also, the parameter should probably still be a NumPy array ...?

And read_raw() should return the buffer instead of having it as an argument.

And finally, I'm having a really hard time imagining a use case for this ...

[bastibe]

read_bytes and write_bytes look good to me. They should simply return/consume bytes. I guess you could use those if you wanted bit-perfect data. You could also use it to very efficiently stream data from one file into another without the overhead of converting to and from Numpy.

[mgeier]

I created an issue for that: #25.

BTW, I think the overhead caused by NumPy (using frombuffer()) is negligible in most cases.

Anyway, I don't see a reason why not to provide this feature.