Soundhub Utils

Audio processing utilities library for SoundHub model integration. This package provides core functionality for:

1. Reading audio files from AWS S3, Google Cloud Storage, HTTPS URLs, and local filesystems
2. Standard audio preprocessing (resampling, segmentation, format conversion)
3. Spectrogram generation using multiple backends (TensorFlow, PyTorch, librosa)
4. Unified I/O interface across different storage platforms

Note: This is a utilities library. For running models (like OWL), see soundhub_model_runner.

Table of Contents

• Installation
• Core Modules
• Usage Examples
• Style Guide

Installation

Using Pixi (Recommended for Development)

Requirements are managed through Pixi. Install pixi, then:

# Run commands in the pixi environment
pixi run python -c "import soundhub_utils; print(soundhub_utils.__version__)"

# Launch jupyter for development
pixi run jupyter lab .

The pyproject.toml includes soundhub_utils = { path = ".", editable = true }, so no separate installation is needed.

Using pip

# Install from local directory
pip install -e .

# Or install specific version (when published to PyPI)
pip install soundhub-utils

Core Modules

I/O (soundhub_utils.io)

Unified interface for reading/writing audio files across multiple storage platforms:

• soundhub_utils.io.aws: AWS S3 integration with partial FLAC download support
• soundhub_utils.io.gcs: Google Cloud Storage operations
• soundhub_utils.io.local: Local filesystem operations
• soundhub_utils.io.url: HTTP/HTTPS streaming and downloads
• soundhub_utils.io.io: Unified interface that auto-routes based on URI scheme

Audio Processing (soundhub_utils.audio)

Audio processing backends for spectrogram generation and preprocessing:

• soundhub_utils.audio.tensorflow_audio: TensorFlow-native audio processing

Utilities (soundhub_utils.utils)

Helper functions for audio processing:

• soundhub_utils.utils.audio: Format conversion and validation
• soundhub_utils.utils.flac: FLAC metadata extraction and time-range processing
• soundhub_utils.names: File naming conventions for audio and spectrograms

Usage Examples

Reading Audio from Different Sources

from soundhub_utils.io import io

# Read from S3
audio_data = io.read_flac("s3://bucket/path/audio.flac")

# Read from Google Cloud Storage
audio_data = io.read_flac("gs://bucket/path/audio.flac")

# Read from HTTPS URL
audio_data = io.read_flac("https://example.com/audio.flac")

# Read from local file
audio_data = io.read_flac("/path/to/audio.flac")

# Read partial FLAC (time range)
audio_data = io.read_partial_flac(
    "s3://bucket/audio.flac",
    start_time=10.0,  # seconds
    duration=30.0      # seconds
)

Generating Spectrograms

from soundhub_utils.audio import tensorflow_audio

# Generate spectrograms from audio file
spectrograms = tensorflow_audio.generate_spectrograms(
    audio_path="/path/to/audio.flac",
    sample_rate=8000,
    segment_duration=12.0,
    spectrogram_shape=[257, 1000]
)

Style Guide

Following PEP8. See setup.cfg for exceptions. Use pycodestyle . to check compliance.

License

BSD 3-Clause