aiaudio

---

Table of Contents

• What is AIAudio?
• Current Features
• Installation
• Quick Start
• Library API
  • Loading Audio
  • Audio Properties
  • Slicing
  • Concatenation
  • Volume Control
  • Resampling
  • Channel Conversion
  • Exporting
  • Chaining Operations
• CLI Reference
  • info
  • slice
  • volume
  • concat
  • convert
• Roadmap
• Project Structure
• Design Principles
• Running Tests
• Contributing
• License

---

What is AIAudio?

AIAudio is a Python library designed to grow with you. At its core it is a simple, clean alternative to Pydub for audio manipulation — no heavy dependencies, just numpy and scipy. As it matures it becomes an AI-powered platform that can transcribe speech, remove background noise, detect speakers, search audio archives by meaning, and generate meeting summaries — all behind the same consistent API.

from aiaudio import Audio

# today
audio = Audio.load("meeting.mp3")
audio.slice(0, 60).export("intro.wav")

# tomorrow (coming phases)
audio.clean()
audio.transcribe()
audio.identify_speakers()
audio.summarize()
audio.export_report("meeting_report.md")

---

Current Features

---

Installation

Core — WAV support, zero heavy dependencies:

pip install aiaudio

With multi-format support (MP3, FLAC, OGG, AAC, M4A):

Requires FFmpeg installed on your system.

# Install FFmpeg first:
winget install ffmpeg          # Windows
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Ubuntu / Debian

# Then:
pip install aiaudio

With GUI (drag-and-drop format converter):

pip install "aiaudio[gui]"

With AI features (transcription, noise removal, embeddings):

pip install "aiaudio[ai]"

For development / contributing:

git clone https://github.com/shubham10divakar/aiaudio.git
cd aiaudio
pip install -e ".[dev]"
pytest   # 48 tests, all green

---

Quick Start

from aiaudio import Audio

# Load any format
audio = Audio.load("podcast.mp3")

print(audio)
# Audio(duration=1823.40s, sample_rate=44100Hz, channels=2)

# Trim to the first 5 minutes
intro = audio.slice(0, 300)

# Boost volume by 3 dB
intro = intro.increase_volume(3)

# Export as FLAC
intro.export("intro.flac")

---

Library API

Loading Audio

from aiaudio import Audio

# WAV — native, no FFmpeg needed
audio = Audio.load("song.wav")

# Any other format — requires FFmpeg
audio = Audio.load("podcast.mp3")
audio = Audio.load("interview.flac")
audio = Audio.load("recording.m4a")
audio = Audio.load("track.ogg")
audio = Audio.load("voice.aac")

---

Audio Properties

audio = Audio.load("song.wav")

audio.duration      # 183.42  (float, seconds)
audio.sample_rate   # 44100   (int, Hz)
audio.channels      # 2       (int, 1=mono / 2=stereo)

print(audio)
# Audio(duration=183.42s, sample_rate=44100Hz, channels=2)

---

Slicing

Extract any segment by start and end time in seconds.

audio = Audio.load("song.wav")

# Extract seconds 10–20
clip = audio.slice(10, 20)

# Extract the first 30 seconds
intro = audio.slice(0, 30)

# Extract the last 60 seconds
outro = audio.slice(audio.duration - 60, audio.duration)

clip.export("clip.wav")

Note: All operations return a new Audio object — the original is never modified.

---

Concatenation

Join any number of Audio objects using the + operator. Both sides must have the same sample rate.

intro = Audio.load("intro.wav")
main  = Audio.load("main.wav")
outro = Audio.load("outro.wav")

full = intro + main + outro

print(full.duration)  # sum of all three
full.export("full_episode.wav")

Mismatched sample rates raise a clear error:

a = Audio.load("44100hz.wav")   # 44100 Hz
b = Audio.load("22050hz.wav")   # 22050 Hz

a + b
# ValueError: Sample rates must match: 44100 vs 22050
# Fix: b = b.resample(44100)

---

Volume Control

Adjust loudness in decibels. Positive dB = louder, negative dB = quieter. Clipping is handled automatically.

audio = Audio.load("quiet_recording.wav")

louder  = audio.increase_volume(6)    # +6 dB  (~2× louder)
quieter = audio.decrease_volume(3)    # -3 dB  (~half as loud)

# Or pass a negative number directly
softer = audio.increase_volume(-6)

louder.export("louder.wav")

---

Resampling

Change the sample rate — useful before export or when concatenating clips with different rates.

audio = Audio.load("hifi.wav")   # 48000 Hz

# Downsample for voice / podcast use
voice = audio.resample(16000)
web   = audio.resample(22050)
cd    = audio.resample(44100)

voice.export("voice.wav")

---

Channel Conversion

Convert between mono and stereo.

stereo = Audio.load("stereo.wav")

# Stereo → mono (averages both channels)
mono = stereo.set_channels(1)

# Mono → stereo (duplicates the single channel)
back = mono.set_channels(2)

mono.export("mono.wav")

---

Exporting

Export to any supported format. The format is inferred from the file extension. WAV works with no extra dependencies; all other formats require FFmpeg.

audio = Audio.load("input.mp3")

audio.export("output.wav")    # native, no FFmpeg
audio.export("output.mp3")    # requires FFmpeg
audio.export("output.flac")   # requires FFmpeg
audio.export("output.ogg")    # requires FFmpeg
audio.export("output.aac")    # requires FFmpeg
audio.export("output.m4a")    # requires FFmpeg

---

Chaining Operations

All methods return a new Audio object, so you can chain freely:

from aiaudio import Audio

result = (
    Audio.load("raw_interview.mp3")
    .slice(30, 1800)           # skip intro, take 30 min
    .set_channels(1)           # convert to mono
    .resample(16000)           # downsample for speech processing
    .decrease_volume(2)        # slightly quieter
)

result.export("interview_processed.wav")

---

CLI Reference

After installing AIAudio the aiaudio command is available globally in your terminal.

aiaudio --help
aiaudio --version

---

aiaudio info

Display metadata about an audio file.

aiaudio info <file>

$ aiaudio info podcast.mp3

File:        podcast.mp3
Duration:    1823.40s
Sample rate: 44100 Hz
Channels:    2

---

aiaudio slice

Extract a segment of audio by start and end time in seconds.

aiaudio slice <file> <start> <end> -o <output>

# Extract seconds 60–120
aiaudio slice podcast.mp3 60 120 -o segment.wav

# Extract the first 30 seconds
aiaudio slice podcast.mp3 0 30 -o intro.wav

# Extract minutes 5–10
aiaudio slice podcast.mp3 300 600 -o middle.wav

---

aiaudio volume

Increase or decrease volume in decibels.

aiaudio volume <file> <db> -o <output>

# Louder (+5 dB)
aiaudio volume quiet.wav 5 -o louder.wav

# Quieter (-3 dB)
aiaudio volume loud.wav -3 -o quieter.wav

---

aiaudio concat

Join two or more audio files in order.

aiaudio concat <file1> <file2> ... -o <output>

# Join two files
aiaudio concat intro.wav main.wav -o full.wav

# Join three or more
aiaudio concat intro.wav part1.wav part2.wav outro.wav -o episode.wav

---

aiaudio convert

Convert audio to a different format. Requires FFmpeg. The output format is inferred from the output file's extension.

aiaudio convert <file> -o <output> [--sample-rate HZ] [--channels {1,2}]

# MP3 → FLAC
aiaudio convert podcast.mp3 -o podcast.flac

# WAV → MP3, downsampled to 22050 Hz
aiaudio convert recording.wav -o recording.mp3 --sample-rate 22050

# Stereo FLAC → mono WAV at 16 kHz (ready for speech processing)
aiaudio convert stereo.flac -o mono_16k.wav --sample-rate 16000 --channels 1

# M4A → OGG
aiaudio convert audiobook.m4a -o audiobook.ogg

---

Roadmap

AIAudio is built in phases. Each phase is independently useful and ships as a working release.

Phase 3 preview — Audio Effects

audio = Audio.load("recording.wav")

audio.fade_in(2000)       # 2-second fade in
audio.fade_out(3000)      # 3-second fade out
audio.normalize()         # peak normalize to 0 dBFS
audio.reverse()           # reverse the audio
audio.speed(1.5)          # 1.5× speed (no pitch change)
audio.remove_silence()    # strip silent gaps

Phase 4 preview — AI Enhancement

audio = Audio.load("noisy_podcast.mp3")

clean = audio.remove_noise()    # deep learning noise suppression
clean = audio.remove_echo()     # echo / reverb reduction
clean = audio.clean()           # full pipeline: noise + echo + background

clean.export("podcast_clean.mp3")

Phase 5 preview — Speech Intelligence

audio = Audio.load("interview.mp3")

transcript = audio.transcribe()
# "Welcome to the show. Today we are talking about..."

lang = audio.detect_language()
# "en"

speakers = audio.identify_speakers()
# [{"speaker": "A", "start": 0.0, "end": 12.4},
#  {"speaker": "B", "start": 12.4, "end": 28.1}, ...]

Phase 6 preview — Embeddings & Search

audio = Audio.load("podcast.mp3")

# Semantic search across your audio
audio.search("discussion about climate change")
# [{"start": 342.1, "end": 398.6, "score": 0.94}, ...]

# Generate an embedding vector for downstream ML
embedding = audio.embed()   # numpy array

Phase 7 preview — AI Workflows

audio = Audio.load("team_meeting.mp3")

print(audio.summarize())
# "The team discussed Q3 targets, identified a blocker in the
#  API integration, and agreed to reconvene Thursday."

print(audio.extract_actions())
# ["John to send API docs by Wednesday",
#  "Sarah to review the staging environment",
#  "Team sync scheduled for Thursday 10am"]

audio.generate_minutes()   # returns structured markdown

Phase 10 preview — Agentic Pipeline

audio = Audio.load("board_meeting.mp3")

audio.clean()
audio.transcribe()
audio.identify_speakers()
audio.extract_actions()
audio.summarize()
audio.export_report("board_meeting_report.md")

# Produces a complete markdown report:
# - Full transcript with speaker labels
# - Executive summary
# - Action items by owner
# - Key topics and timestamps

---

Project Structure

aiaudio/
│
├── core/
│   ├── audio.py        # Audio class — the main user-facing object
│   ├── loader.py       # Format detection, WAV read, FFmpeg decode
│   ├── exporter.py     # WAV write, FFmpeg encode
│   └── ffmpeg.py       # FFmpeg subprocess bridge (probe, load, export)
│
├── cli/
│   └── main.py         # aiaudio CLI — argparse subcommands
│
├── effects/            # Phase 3 — fade, normalize, reverse, silence
├── ai/                 # Phases 4–7 — enhancer, whisper, diarization, LLM
├── gui/                # Phase 2.5 — Gradio format converter
├── plugins/            # Phase 9 — plugin registry
└── utils/

tests/
├── test_core.py        # Phase 1 — 22 tests
├── test_cli.py         # Phase 1.1 — 9 tests
└── test_phase2.py      # Phase 2 — 17 tests (8 skipped if FFmpeg absent)

setup.py
pyproject.toml
README.md
AIAUDIO_PLAN.md         # full phased plan with API sketches and UI mockups

---

Design Principles

Immutable API Every method returns a new Audio object. The original is never modified, so you can branch freely without defensive copying.

original = Audio.load("song.wav")
louder   = original.increase_volume(6)   # new object
clip     = original.slice(10, 20)        # original still untouched

Lean core, optional extras The core library installs in seconds — only numpy and scipy. Heavy ML dependencies (PyTorch, Whisper, Demucs) only arrive when you opt in:

pip install aiaudio           # core only (~10 MB)
pip install "aiaudio[ai]"     # adds torch + whisper + more

One code path The CLI and (future) GUI are thin orchestration layers. All logic lives in the Audio class. There is no special-casing for how a request arrived.

Float32 internally Samples are normalised to [-1.0, 1.0] on load regardless of source bit depth. All DSP math operates in float32. Conversion back to int16 happens only on WAV export.

Format-transparent Audio.load("file.mp3") and Audio.load("file.wav") have identical return types and behave identically. The format routing is invisible to the caller.

---

Running Tests

# Run all tests
pytest

# Verbose output
pytest -v

# With coverage report
pytest --cov=aiaudio --cov-report=term-missing

# Core only (no FFmpeg needed)
pytest tests/test_core.py tests/test_cli.py -v

FFmpeg integration tests skip automatically if FFmpeg is not installed — they do not fail.

48 passed, 8 skipped   ← skipped = FFmpeg not present
56 passed, 0 skipped   ← when FFmpeg is installed

---

Contributing

Contributions are welcome. The project follows a phase-by-phase build order — see AIAUDIO_PLAN.md for the full roadmap and API design for upcoming phases.

1. Fork the repo and create a branch from main
2. Install dev dependencies: pip install -e ".[dev]"
3. Make your changes and add tests
4. Ensure all tests pass: pytest
5. Open a pull request

---

License

MIT — free to use, modify, and distribute.

---