pydub-stubs

Warnings

• gotcha pydub requires external (non-Python) dependencies like FFmpeg or libav for processing most audio formats (e.g., MP3, FLAC, OGG). Without them, it can only handle WAV files. These must be installed separately and made available in your system's PATH.
  Fix: Install FFmpeg or libav from their official sources and add their binary directory to your system's PATH environment variable.
• gotcha Some pydub functions, especially certain effects, are dynamically added to the `AudioSegment` class at runtime. While `pydub-stubs` attempts to type these using overloads, some dynamically added methods might not be perfectly typed or accessible via direct import from submodules like `pydub.effects` if your type checker expects them on `AudioSegment` directly.
  Fix: Refer to the pydub documentation for the canonical way to use such functions. If type checking fails, consider using `# type: ignore` for specific lines or checking `pydub.effects` directly for the function if it's not present on `AudioSegment`.
• deprecated The underlying `pydub` library utilizes standard library modules like `audioop`, which are slated for deprecation in Python 3.13. This may lead to deprecation warnings when using `pydub` (and implicitly, `pydub-stubs`) with newer Python versions.
  Fix: Monitor the pydub and pydub-stubs GitHub repositories for updates that address Python 3.13 compatibility. There might be alternative 'audioop-lts' packages or similar solutions emerging.
• gotcha Version numbers for stub packages like `pydub-stubs` are often structured (e.g., `major.minor.patch.stubs_version`). The `major.minor.patch` parts correspond to the version of the runtime package (`pydub`) they target. Discrepancies between the installed `pydub` version and the `pydub-stubs` version can lead to incorrect type hints or type checking failures.
  Fix: Ensure that the `pydub-stubs` version you install is compatible with your installed `pydub` version. It's often best to pin the `pydub-stubs` version to match your `pydub` version's major and minor components if issues arise.
• gotcha pydub frequently uses temporary files for conversions and intermediate processing. Users may encounter `FileNotFoundError` or `PermissionError` if the Python process lacks write permissions in the default temporary directory or the specified output directory.
  Fix: Ensure the user running the script has appropriate read/write permissions for the temporary directory (often specified by `TMPDIR` or `TEMP` environment variables) and any output directories. On Windows, this can sometimes be resolved by adjusting folder permissions or running as administrator. Setting the `TMPDIR` environment variable to a writable path can also help.

Install

• pip install pydub-stubs Install pydub-stubs

Imports

• AudioSegment

  from pydub import AudioSegment

• play

  from pydub.playback import play

• effects

  import pydub.effects

  Some effect functions are dynamically added to AudioSegment at runtime and may not be directly importable from pydub.

Quickstart

This quickstart demonstrates basic pydub functionality: loading an audio file, applying a simple effect (volume boost), and exporting the result. It uses a programmatically generated WAV file to ensure the example is runnable without external downloads. For handling common formats like MP3, FLAC, or OGG, ensure `ffmpeg` or `libav` is installed and accessible in your system's PATH.

from pydub import AudioSegment
from pydub.playback import play
import os

# Create a dummy silent WAV file for demonstration
silent_audio = AudioSegment.silent(duration=1000) # 1 second of silence
silent_audio.export("input.wav", format="wav")

# Load an audio file (replace with your actual file if not using dummy)
song = AudioSegment.from_file("input.wav", format="wav")

# Boost volume by 6 dB
louder_song = song + 6

# Export the modified audio
louder_song.export("output.wav", format="wav")

# Play the original and louder song (requires simpleaudio or similar for playback)
# print("Playing original song...")
# play(song)
# print("Playing louder song...")
# play(louder_song)

print("Original and louder audio files created as input.wav and output.wav")
print("Note: For non-WAV formats (like MP3), pydub requires ffmpeg or libav to be installed and in your system PATH.")

# Clean up dummy files
os.remove("input.wav")
os.remove("output.wav")