audiolab

A Python library for audio processing built on top of soundfile, and PyAV (bindings for FFmpeg). audiolab provides a simple and efficient interface for loading, processing, and saving audio files.

Features

• Load audio from multiple sources: local paths, HTTP URLs, bytes, and BytesIO streams
• Load audio files in various formats (WAV, MP3, FLAC, AAC, etc.)
• Save audio files in different container formats
• Support for audio streaming and real-time processing (resampling, speeding up, and other filters)
• Command-line interface for audio file inspection
• Support for audio transformations and filtering

Installation

pip install audiolab

Quick Start

Load an audio file

from audiolab import load_audio

# Load audio from 7 to 30 seconds (duration: 23s) and convert to 16kHz mono
audio, rate = load_audio("audio.wav", offset=7, duration=23, rate=16000, to_mono=True)
print(f"Sample rate: {rate} Hz")
print(f"Audio shape: {audio.shape}")

Save an audio file

import numpy as np
from audiolab import save_audio

# Create a simple sine wave
rate = 44100
duration = 5
t = np.linspace(0, duration, rate * duration)
audio = np.sin(2 * np.pi * 440 * t)

# Save as WAV file
save_audio("tone.wav", audio, rate)

Get audio file information

from audiolab import info

# Get information about an audio file
print(info("audio.wav"))

Command-line usage

# Get information about an audio file
audi audio.wav

# Show only specific information
audi -r -c audio.wav  # Show sample rate and channels only
audi -d audio.wav     # Show duration in hours, minutes and seconds
audi -D audio.wav     # Show duration in seconds

# Get audio information from URL
audi https://modelscope.cn/datasets/pengzhendong/filesamples/resolve/master/audio/m4a/sample1.m4a

Input File     : 'https://modelscope.cn/datasets/pengzhendong/filesamples/resolve/master/audio/m4a/sample1.m4a' (mov,mp4,m4a,3gp,3g2,mj2)
Channels       : 2
Sample Rate    : 44100
Precision      : 32-bit
Duration       : 00:02:02.093 = 5384301 samples ~ 9156.97 CDDA sectors
File Size      : 2 MB
Bit Rate       : 131.8 kbps
Sample Encoding: AAC (Advanced Audio Coding)
Comments       :
    major_brand: M4A
    minor_version: 512
    compatible_brands: isomiso2
    encoder: Lavf57.83.100
    language: und
    handler_name: SoundHandler
    vendor_id: [0][0][0][0]

CLI Options

• -f, --forced-decoding Forced decoding the audio file to get the duration
• -t, --show-file-type Show detected file-type
• -r, --show-sample-rate Show sample-rate
• -c, --show-channels Show number of channels
• -s, --show-samples Show number of samples (N/A if unavailable)
• -d, --show-duration-hms Show duration in hours, minutes and seconds (N/A if unavailable)
• -D, --show-duration-seconds Show duration in seconds (N/A if unavailable)
• -b, --show-bits-per-sample Show number of bits per sample (N/A if not applicable)
• -B, --show-bitrate Show the bitrate averaged over the whole file (N/A if unavailable)
• -p, --show-precision Show estimated sample precision in bits
• -e, --show-encoding Show the name of the audio encoding
• -a, --show-comments Show file comments (annotations) if available
• --help Show this message and exit

If no specific options are selected, all information will be displayed by default.

API Overview

Core Functions

• load_audio(): Load audio from file
• save_audio(): Save audio to file
• info(): Get information about an audio file
• encode(): Transform audio to PCM bytestring

Classes

• Reader: Read audio files with advanced options
• StreamReader: Read audio streams
• Writer: Write audio files with custom parameters

Advanced Usage

Apply filters during loading

from audiolab import info, load_audio
from audiolab.av.filter import aresample, asetrate, atempo

# Speed perturbation
filters = [atempo(1.5)]
audio, rate = load_audio("audio.wav", filters=filters)

# Pitch perturbation
ratio = 1.5
rate = info("audio.wav").rate
filters = [asetrate(rate * ratio), atempo(1 / ratio), aresample(rate)]
audio, rate = load_audio("audio.wav", filters=filters)

Streaming processing

import numpy as np
from audiolab.av.filter import atempo
from audiolab import AudioPipe, Reader, save_audio

frames = []
reader = Reader("audio.wav")
pipe = AudioPipe(in_rate=reader.rate, filters=[atempo(2)])
for frame, _ in reader:
    pipe.push(frame)
    for frame, _ in pipe.pull():
        frames.append(frame)
for frame, _ in pipe.pull(True):
    frames.append(frame)
save_audio("output.wav", np.concatenate(frames, axis=1), reader.rate)

License

Apache License 2.0