Skip to content

Documentation clarifications #410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@ To build binary wheels for all supported platforms, run ``python
build_wheels.py``, which will ``python setup.py bdist_wheel`` for each
of the platforms we have precompiled libsndfiles for.

To build the documentation, install Sphinx and the ReadTheDocs theme
(``pip install sphinx sphinx-rtd-theme``) and run the Makefile in ``doc/``.

Error Reporting
---------------

Expand Down
21 changes: 14 additions & 7 deletions soundfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -307,12 +307,18 @@ def write(file, data, samplerate, subtype=None, endian=None, format=None,

.. note:: The data type of *data* does **not** select the data
type of the written file. Audio data will be
converted to the given *subtype*. Writing int values
to a float file will *not* scale the values to
[-1.0, 1.0). If you write the value ``np.array([42],
dtype='int32')``, to a ``subtype='FLOAT'`` file, the
file will then contain ``np.array([42.],
dtype='float32')``.
converted to the given *subtype*, with these caveats:

* Writing int values to a float file will *not* scale the
values to [-1.0, 1.0). If you write the value
``np.array([42], dtype='int32')``, to a ``subtype='FLOAT'``
file, the file will then contain ``np.array([42.],
dtype='float32')``.
* For pure Python (non-Numpy) input values, floats will
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this wording could be misunderstood. I would rephrase it as "floats are expected in in the range ... and integers in the range ...".

be scaled from the range [-1.0, 1.0) and integers will
be scaled from the int64 range, [``-2**63``, ``2**63``).
Since the int64 range is probably not what you want, using
floats is recommended.

samplerate : int
The sample rate of the audio data.
Expand Down Expand Up @@ -1033,7 +1039,8 @@ def buffer_write(self, data, dtype):
----------
data : buffer or bytes
A buffer or bytes object containing the audio data to be
written.
written. For bytes the data will be interpreted according to the
system endianness, ``sys.byteorder``.
dtype : {'float64', 'float32', 'int32', 'int16'}
The data type of the audio data stored in *data*.

Expand Down