Skip to main content

Waddle 🦆

Waddle is an open-source podcast production toolkit that converts raw audio recordings into production-ready episodes. Originally created for RubberDuck.fm, Waddle automates common podcast production tasks.

It handles multi-speaker audio alignment, noise removal, transcription, and chapter generation. Waddle provides a structured workflow for podcast production.

waddle

Features

  • Alignment: Automatically synchronizes the audio files of each speaker to ensure they are perfectly aligned with the reference audio.
  • Normalization: Ensures consistent audio quality by normalizing audio levels.
  • Remove Noise: Cleans up audio by reducing background noise for clearer output using DeepFilterNet.
  • Subtitle Generation: Generates SRT subtitle files for transcription using whisper.cpp.
  • Metadata Generation: Processes annotated SRT files to create chapter markers and show notes for podcast episodes.

Prerequisites

Waddle requires Python 3.13 or higher. All other dependencies can be installed automatically using the waddle install command.

Installation

  1. Install waddle via pip:

    pip install waddle-ai
    
  2. Install all required tools and dependencies:

    waddle install
    
  3. You're ready to use Waddle!

Manual Installation (Optional)

If you prefer to install dependencies manually:

  1. Python 3.13 or higher:

  2. FFmpeg:

    • MacOS:
      brew install ffmpeg
      
    • Ubuntu/Debian:
      sudo apt update
      sudo apt install ffmpeg
      
    • Windows:
      • Download and install FFmpeg from FFmpeg Downloads.
      • Ensure FFmpeg is added to your system's PATH.
  3. Dependencies for compiling whisper.cpp:

    • CMake:

      • MacOS:
        brew install cmake
        
      • Ubuntu/Debian:
        sudo apt update
        sudo apt install cmake
        
    • fmt:

      • MacOS:
        brew install fmt
        
      • Ubuntu/Debian:
        sudo apt update
        sudo apt install libfmt-dev
        
Development Installation

For developers who want to contribute to Waddle, see CONTRIBUTING.md for detailed setup instructions.

Waddle Flow

Waddle Flow is the recommended workflow for podcast production using Waddle. It follows a structured approach through five stages, each with its own directory:

Initialize Project

First, create a new project with the 5-stage folder structure:

waddle init EPISODE_NUM
cd EPISODE_NUM

This creates the following directories:

  • 0_raw/ - Raw audio files
  • 1_pre/ - Preprocessed audio files
  • 2_edited/ - Manually edited audio files
  • 3_post/ - Post-processed audio files
  • 4_meta/ - Metadata files

Stage 0: Raw (0_raw/)

Place your original audio recordings here:

  • Upload each speaker's audio files using the naming convention: ep{N}-{SpeakerName}.[wav|aifc|m4a|mp4]
    • Example: ep1-Alice.wav, ep1-Bob.aifc
  • Include a reference audio file that covers the entire podcast. The reference file name must start with GMT (e.g., a Zoom recording)
    • Example: GMT-recording.wav

Stage 1: Preprocessed (1_pre/)

Use the preprocess command to align and clean audio files:

waddle preprocess

This stage produces aligned and cleaned audio files.

Stage 2: Edited (2_edited/)

Manual editing stage for fine-tuning:

  • Edit files from 1_pre/ using your preferred audio editor
  • Remove unwanted sections, adjust levels, add effects
    • If you want to edit with transcription, you can run waddle preprocess -tr to generate SRT files for each speaker.
  • Save edited files here

Stage 3: Post-processed (3_post/)

Use the postprocess command to finalize audio:

waddle postprocess

This stage produces:

  • Final merged audio
  • Transcription (SRT files)

Stage 4: Metadata (4_meta/)

Edit the SRT files in 3_post/ to add chapter markers and show notes. Then, generate podcast metadata:

waddle metadata

This stage produces:

  • Chapter markers
  • Show notes
  • MP3 with embedded metadata

Then you can upload the final audio and metadata to your podcast hosting platform.

Complete Workflow Example

# Initialize project
waddle init my-podcast
cd my-podcast

# Place raw files in 0_raw/
cp ~/recordings/* 0_raw/

# Stage 1: Preprocess
waddle preprocess

# Stage 2: Manual editing (use your audio editor such as Audacity)
# Edit files from 1_pre/ and save to 2_edited/

# Stage 3: Post-process  
waddle postprocess

# Edit 3_post/{episode_name}.srt to add chapter markers and show notes
# Example:
# 
# 1
# 00:00:00.000 --> 00:00:03.000
# alice: Welcome to our podcast!
#
# # Programming Discussion
#
# 2
# 00:00:03.000 --> 00:00:06.000
# bob: Today we'll discuss programming.
#
# - [Rust Language](https://rust-lang.org)

# Stage 4: Generate metadata
waddle metadata

Commands

  • init - Initialize a new waddle project with folder structure:

    waddle init [project_name]
    
    • project_name (optional): Name of the project directory. If not provided, creates folders in the current directory.
    • Creates the following folder structure:
      • 0_raw/ - Raw audio files
      • 1_pre/ - Preprocessed audio files
      • 2_edited/ - Manually edited audio files
      • 3_post/ - Post-processed audio files
      • 4_meta/ - Metadata files
  • install - Install all required tools and dependencies:

    waddle install
    

    Automatically installs FFmpeg, CMake, fmt, DeepFilterNet, and whisper.cpp based on your platform (macOS/Linux).

  • single - Process a single audio file:

    waddle single path/to/audio.wav -o ./output
    
    • -o, --output: Directory to save the output (default: ./out).
    • -ss: Start time in seconds for the audio segment (default: 0.0).
    • -t, --time: Duration in seconds for the output audio (default: None).
    • -wo, --whisper-options: Options to pass to Whisper transcription (default: -l ja). You can change the default language by modifying src/config.py.
    • -nnr, --no-noise-remove: Skip removing noise from the audio. (no value required)
  • preprocess - Process multiple audio files:

    waddle preprocess
    
    • -d, --directory: Directory containing audio files (default: 0_raw).
    • -o, --output: Directory to save the output (default: 1_pre).
    • -ss: Start time in seconds for the audio segment (default: 0.0).
    • -t, --time: Duration in seconds for the output audio (default: None).
    • -wo, --whisper-options: Options to pass to Whisper transcription (default: -l ja).
    • -nnr, --no-noise-remove: Skip removing noise from the audio. (no value required)
    • -r, --reference: Path to the reference audio file (used in multi-file mode).
    • -c, --comp-duration: Duration in seconds for alignment comparison (default: 1200.0s).
    • -nc, --no-convert: Skip converting audio files to WAV format. (no value required)
    • -tr, --transcribe: Transcribe the processed audio files. (no value required)
  • postprocess - Process aligned audio files:

    waddle postprocess
    
    • -d, --directory: Directory containing audio files (default: 2_edited).
    • -o, --output: Directory to save the output (default: 3_post).
    • -ss: Start time in seconds for the audio segment (default: 0.0).
    • -t, --time: Duration in seconds for the output audio (default: None).
    • -wo, --whisper-options: Options to pass to Whisper transcription (default: -l ja).
  • metadata - Generate metadata from an annotated SRT file:

    waddle metadata
    
    • source (optional): Path to the annotated SRT file (default: looks for SRT files in 3_post/).
    • -i, --input: Path to the input audio file. If not specified, it will look for an audio file with the same name.
    • -o, --output: Directory to save the metadata and audio files (default: 4_meta).

Annotated SRT Format

When using the metadata command, your SRT file should include annotations:

  • # Chapter markers define chapters (up to 6 levels with #)
  • Chapter starts at the next SRT timestamp and ends before the next chapter
  • Any other text is considered show notes
  • Empty lines are ignored
  • Use ; to add newlines in show notes (the ; will be deleted)

Example

# Introduction

1
00:00:00.000 --> 00:00:03.000
alice: Welcome to our podcast!

2
00:00:03.000 --> 00:00:06.000
bob: Today we'll discuss programming.

## Topic 1: Rust

3
00:00:06.000 --> 00:00:09.000
alice: Let's talk about Rust.

- [Rust Language](https://rust-lang.org)
;
Great for systems programming!

4
00:00:09.000 --> 00:00:12.000
bob: I love its memory safety.

# Conclusion

5
00:00:12.000 --> 00:00:15.000
alice: Thanks for listening!

Output Files

The above example would generate these files:

  1. chapters.txt:
- (00:00) Introduction
- (00:06) Topic 1: Rust
- (00:12) Conclusion
  1. show_notes.md:
- [Rust Language](https://rust-lang.org)

Great for systems programming!
  1. The chapter markers would also be embedded in the MP3 metadata for podcast apps

Contributing

Want to contribute to Waddle? We welcome contributions! Please see CONTRIBUTING.md for detailed development setup, testing guidelines, and contribution workflows.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for waddle-ai 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for waddle-ai 0.1.5
File Size Uploaded Provenance Actions
waddle_ai-0.1.5.tar.gz 65.9 kB Without provenance Details for waddle_ai-0.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for waddle-ai 0.1.5
File Interpreter ABI Platform Actions
waddle_ai-0.1.5-py3-none-any.whl Python 3 none any Details for waddle_ai-0.1.5-py3-none-any.whl

Total release size: 111.9 kB

Release files / waddle_ai-0.1.5.tar.gz

Download URL waddle_ai-0.1.5.tar.gz
Size 65.9 kB
Tags Source
SHA-256 checksum
How to use checksums
0f22d675dd481027bfa5c667dbaeaa1aa89f0445ed788ebb9830f46568d01592
BLAKE2b-256 checksum
How to use checksums
0bf6d92bac63bcc1d6b098b7a849c7973ba8e6ebb8d29e9fff168f9238c10392
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.7.13

Release files / waddle_ai-0.1.5-py3-none-any.whl

Download URL waddle_ai-0.1.5-py3-none-any.whl
Size 46.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d3a07bb7a264767580c5d9a661159dbde578bb851501944b407e5161fa93e1f
BLAKE2b-256 checksum
How to use checksums
d3737616edc79a2ad9025ffbf0616ec3b481e5427152d19834579727931ed418
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.7.13

Security for waddle-ai 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page