Metadata-Version: 2.1
Name: audiofile
Version: 0.2.4
Summary: Fast reading of all kind of audio files
Home-page: https://github.com/audeering/audiofile
Author: Hagen Wierstorf
Author-email: hwierstorf@audeering.com
License: MIT License
Keywords: audio tools
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Dist: numpy
Requires-Dist: soundfile
Requires-Dist: sox

=========
audiofile
=========

|tests| |docs| |license|

The python package ``audiofile`` provides a meta package to handle all kind of
audio files under Python with a focus on reading speed.

Documentation: https://audiofile.readthedocs.io/

.. |tests| image:: https://travis-ci.org/audeering/audiofile.svg?branch=master
    :target: https://travis-ci.org/audeering/audiofile/
    :alt: audiofile on TravisCI
.. |docs| image:: https://readthedocs.org/projects/audiofile/badge/
    :target: https://audiofile.readthedocs.io/
    :alt: audiofile's documentation on Read the Docs
.. |license| image:: https://img.shields.io/badge/license-MIT-green.svg
    :target: https://github.com/audeering/audiofile/blob/master/LICENSE
    :alt: audiofile's MIT license

Installation
============

It is recommended to first create a Python virtual environment using a tool like
virtualenv_, e.g.

.. code-block:: bash

    virtualenv --python=/usr/bin/python3 --no-site-packages _env
    source _env/bin/activate

Afterwards install ``audiofile`` with

.. code-block:: bash

    pip install audiofile

In order to handle all possible audio files, please make sure ffmpeg_ and
mediainfo_ are installed on your system.

If you want to use Python 2.7 make sure you install the following backports
package as well:

.. code-block:: bash

    pip install backports.tempfile

.. _virtualenv: https://virtualenv.pypa.io/
.. _ffmpeg: https://www.ffmpeg.org/
.. _mediainfo: https://mediaarea.net/en/MediaInfo/

Usage
=====

Import the package and use it to write or read an audio file, or get information
about its metadata:

.. code-block:: python

    import numpy as np
    import audiofile as af

    sampling_rate = 8000  # in Hz
    noise = np.random.normal(0, 1, sampling_rate)
    noise /= np.amax(np.abs(noise))
    af.write('noise.wav', noise, sampling_rate)
    af.channels('noise.wav')
    af.duration('noise.wav')
    sig, fs = af.read('noise.wav')

It should work with every audio file you will work with. WAV, FLAC, and OGG
files are handled by soundfile_. The reading of all other audio files is managed
by converting them to a temporary WAV file by pysox_ or ffmpeg_, which means it
can handle audio from video files as well.

.. _soundfile: https://pysoundfile.readthedocs.io/
.. _pysox: http://pysox.readthedocs.org/
.. _ffmpeg: https://www.ffmpeg.org/

Changelog
=========

All notable changes to this project will be documented in this file.

The format is based on `Keep a Changelog`_,
and this project adheres to `Semantic Versioning`_.


Version 0.2.4 (2020-08-31)
--------------------------

* Fixed: ``CHANGELOG`` format for PyPI server


Version 0.2.3 (2020-08-31)
--------------------------

* Fixed: catch ``SoxiError`` in ``audiofile.read()``
* Fixed: test for more advanced audio files like OPUS, AMR, ...


Version 0.2.2 (2019-10-04)
--------------------------

* Changed: switch to keep a changelog format
* Changed: define package in ``setup.cfg``


Version 0.2.1 (2019-05-02)
--------------------------

* Fixed: module only package


Version 0.2.0 (2019-05-02)
--------------------------

* Changed: improve documentation
* Changed: switch to single ``audiofile.py`` module
* Fixed: skip tests if download fails


Version 0.1.3 (2019-03-27)
--------------------------

* Fixed: metadata samples and duration for MP3 files


Version 0.1.2 (2019-03-25)
--------------------------

* Fixed: metadata for pypi.org


Version 0.1.1 (2019-03-25)
--------------------------

* Fixed: license statement in PyPI package


Version 0.1.0 (2019-03-25)
--------------------------

* Added: First public release


.. _Keep a Changelog: https://keepachangelog.com/en/1.0.0/
.. _Semantic Versioning: https://semver.org/spec/v2.0.0.html


