#!/usr/bin/env python
# coding: utf-8

# # Reading and Writing Audio Files with the `soundfile` module
# 
# [back to overview page](index.ipynb)
# 
# There are many libraries for handling audio files with Python (see [overview page](index.ipynb)), but the best one is probably the [soundfile](http://github.com/bastibe/SoundFile) module.
# 
# Full documentation including installation instructions is available at http://pysoundfile.readthedocs.org/.
# 
# Advantages: 
# 
# * supports many file formats (thanks to libsndfile)
#   * WAV, OGG, FLAC and many more
#   * see [bottom of this notebook](#Available-Formats) for full list of supported formats
# * supports 24-bit PCM and 32-bit floating point WAV files
# * WAVEX support
# * can read parts of audio files
# * automatic type conversion and normalization
# * works in CPython 2.x and 3.x and in PyPy as well
# * provides audio data as NumPy arrays by default, but it can also work with plain Python buffer objects if NumPy is not available
# 
# Disadvantages:
# 
# * no MP3 support
# 
# Installation:
# 
#     python3 -m pip install soundfile

# ## Reading
# 
# This is the quickest way to load a WAV file into a NumPy array (using [soundfile.read()](http://pysoundfile.readthedocs.org/#soundfile.read)):

# In[1]:


import soundfile as sf
sig, samplerate = sf.read('data/test_wav_pcm16.wav')


# That's all. Easy, isn't it?
# 
# But let's have a closer look ...
# 
# The test file is not a very typical file, because it only has 15 frames but it has 7 channels:

# In[2]:


sig.shape


# In[3]:


samplerate


# Let's check the contents of the file by plotting thw audio waveform:

# In[4]:


import matplotlib.pyplot as plt


# In[5]:


plt.plot(sig);


# Looking good!
# 
# In most cases [soundfile.read()](http://pysoundfile.readthedocs.org/#soundfile.read) is all you need, but for some advanced use cases, you might want to use a [soundfile.SoundFile](http://pysoundfile.readthedocs.org/#soundfile.SoundFile) object instead:

# In[6]:


f = sf.SoundFile('data/test_wav_pcm16.wav')


# In[7]:


len(f), f.channels, f.samplerate


# In[8]:


f.format, f.subtype, f.endian


# In[9]:


test = f.read()
test.shape


# In[10]:


plt.plot(test);


# In[11]:


(test == sig).all()


# As you can see, you get the same data as with `sf.read()`.

# In[12]:


# TODO: read mono file
# mono data is by default returned as one-dimensional NumPy array,
# this can be changed with always_2d=True


# 24-bit files work:

# In[13]:


sig, samplerate = sf.read('data/test_wav_pcm24.wav')
plt.plot(sig);


# WAVEX is supported:

# In[14]:


sig, samplerate = sf.read('data/test_wavex_pcm16.wav')
plt.plot(sig);


# In[15]:


sig, samplerate = sf.read('data/test_wavex_pcm24.wav')
plt.plot(sig);


# 32-bit float files work:

# In[16]:


sig, samplerate = sf.read('data/test_wav_float32.wav')
plt.plot(sig);


# In[17]:


sig, samplerate = sf.read('data/test_wavex_float32.wav')
plt.plot(sig);


# ## Writing
# 
# Writing audio data to a file (using [soundfile.write()](http://pysoundfile.readthedocs.org/#soundfile.write)) is as simple as reading from a file:

# In[18]:


sf.write('my_pcm16_file.wav', sig, samplerate)


# Let's check if this file has really been written:

# In[19]:


get_ipython().system('sndfile-info my_pcm16_file.wav')


# Note that by default, WAV files are written as 16-bit fixed point data (a.k.a. `'PCM_16'`).
# You can find the default setting for each file format with [soundfile.default_subtype()](http://pysoundfile.readthedocs.org/#soundfile.default_subtype):

# In[20]:


sf.default_subtype('WAV')


# If you want to save your file with a better quality setting (especially if you want to do further processing later), you can, for example, use the 32-bit floating point format:

# In[21]:


sf.write('my_float_file.wav', sig, samplerate, subtype='FLOAT')


# Let's check if this worked:

# In[22]:


get_ipython().system('sndfile-info my_float_file.wav')


# You can get all available subtypes for a given format with [soundfile.available_subtypes()](http://pysoundfile.readthedocs.org/#soundfile.available_subtypes):

# In[23]:


sf.available_subtypes('WAV')


# ## Available Formats
# 
# You can get all available formats with [soundfile.available_formats()](http://pysoundfile.readthedocs.org/#soundfile.available_formats):

# In[24]:


sf.available_formats()


# ... and all available subtypes with [soundfile.available_subtypes()](http://pysoundfile.readthedocs.org/#soundfile.available_subtypes):

# In[25]:


sf.available_subtypes()


# ## Version Info

# In[26]:


print("PySoundFile version:", sf.__version__)

import sys
print("Python version:", sys.version)


# <p xmlns:dct="http://purl.org/dc/terms/">
#   <a rel="license"
#      href="http://creativecommons.org/publicdomain/zero/1.0/">
#     <img src="http://i.creativecommons.org/p/zero/1.0/88x31.png" style="border-style: none;" alt="CC0" />
#   </a>
#   <br />
#   To the extent possible under law,
#   <span rel="dct:publisher" resource="[_:publisher]">the person who associated CC0</span>
#   with this work has waived all copyright and related or neighboring
#   rights to this work.
# </p>