RAW example in README is severely broken

[bastibe]

There are surprisingly many bugs (even when not counting PEP-8 violations) in this (this is before #132):

import soundfile as sf

format = {'format':'RAW', 'subtype':'FLOAT', 'endian':'FILE'}
data = sf.read('myfile.raw', dtype='float32', **format)
sf.write(data, 'otherfile.raw', **format)

This would be a variation that actually works (after merging #132):

import soundfile as sf

format = dict(format='RAW', subtype='FLOAT', endian='FILE', samplerate=44100)
data, samplerate = sf.read('myfile.raw', channels=1, dtype='float32', **format)
assert samplerate == format['samplerate']
sf.write('otherfile.raw', data, **format)

Given this complexity, this is probably not such a "useful idiom" after all?

I hereby suggest to remove this example and replace it with an example for just reading a RAW file, which will show that all those arguments have to be given even for reading.

Reading RAW files is much more important than writing them, anyway.

[bastibe]

Yes, I agree!

[mgeier]

@bastibe do you want to do that?

[bastibe]

Sure

[bastibe]

I still think that the RAW example is useful, even with the "dict trick". RAW files are inherently complex to deal with, so a bit of inelegance is not a big problem I'd say.

[mgeier]

I agree that having an example for RAW is useful, but the current one is much too complicated and more confusing than helpful.

To a beginner should not be suggested that writing a RAW file is generally a good idea, so it would be best if we don't show this in an example. OTOH, a beginner might well be confronted with a RAW file from somebody else, and it would be extremely helpful to see an example how to read a RAW file.

import soundfile as sf

data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100,
                           subtype='FLOAT')

To be honest, I have no clue what endian='FILE' is supposed to mean for RAW files, do you?
When I tried it, the default seemed to be endian='LITTLE', but I have no idea if this is platform-dependent.
To make this clear, we should probably show an explicit endian-ness like endian='LITTLE' ...?

import soundfile as sf

data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100,
                           subtype='FLOAT', endian='LITTLE')

And then we could even mention, that the user should find out by trial and error if endian='LITTLE' or endian='BIG' is the right thing for the file at hand.

[bastibe]

x86 is little-endian, so the default argument makes perfect sense, and should be correct in most cases.

I agree that writing RAW should be discouraged, and added a note to that effect to the README.

[mgeier]

Cool.

You could even explicitly state the alternative with "... have to use ``endian='BIG'``."