{"library":"pydub","title":"Pydub Audio Manipulation","description":"Pydub is a high-level Python library designed for simple and easy audio manipulation. It provides an intuitive interface for tasks like playing, slicing, concatenating, and editing audio files, supporting formats such as WAV, MP3, and FLAC. The current stable version is 0.25.1, released on March 9, 2021, and the library is actively maintained for modern Python versions (>=3.6).","status":"active","version":"0.25.1","language":"en","source_language":"en","source_url":"https://github.com/jiaaro/pydub","tags":["audio","sound","manipulation","ffmpeg","encoding","decoding","editing"],"install":[{"cmd":"pip install pydub","lang":"bash","label":"Install pydub"}],"dependencies":[{"reason":"External system dependency required for processing most audio formats (MP3, FLAC, OGG, etc.). WAV files work without it. Must be installed separately and available in system PATH.","package":"ffmpeg / libav","optional":false},{"reason":"Optional Python library for audio playback functionality.","package":"simpleaudio","optional":true},{"reason":"Optional Python library for audio playback functionality (alternative to simpleaudio).","package":"pyaudio","optional":true},{"reason":"Optional Python library for advanced audio filters and effects.","package":"scipy","optional":true}],"imports":[{"note":"AudioSegment is the primary class for representing and manipulating audio data.","symbol":"AudioSegment","correct":"from pydub import AudioSegment"}],"quickstart":{"code":"from pydub import AudioSegment\n\n# Create a dummy audio file for the example (replace with your actual file)\n# This part requires ffmpeg if you want to export to mp3/other formats.\n# For pure WAV, pydub can handle it natively.\ntry:\n    # Attempt to create a simple silent WAV file if no external file exists\n    one_second_of_silence = AudioSegment.silent(duration=1000)\n    one_second_of_silence.export(\"input.wav\", format=\"wav\")\n    print(\"Created a dummy 'input.wav' file.\")\nexcept Exception as e:\n    print(f\"Could not create dummy WAV: {e}. Please provide an existing audio file or ensure ffmpeg is installed for non-WAV formats.\")\n\n# --- Pydub operations ---\n\n# Load an audio file (e.g., input.wav or input.mp3)\n# If you use .mp3, make sure ffmpeg is installed and in your PATH.\ntry:\n    song = AudioSegment.from_file(\"input.wav\", format=\"wav\")\n    print(f\"Loaded audio segment. Duration: {len(song) / 1000.0} seconds.\")\n\n    # Increase volume by 6 dB\n    louder_song = song + 6\n\n    # Add a 2-second fade in and 3-second fade out\n    faded_song = louder_song.fade_in(2000).fade_out(3000)\n\n    # Export the manipulated audio to a new file\n    output_filename = \"output.mp3\"\n    faded_song.export(output_filename, format=\"mp3\")\n    print(f\"Exported '{output_filename}' successfully.\")\n\n    # To play the audio (requires simpleaudio or pyaudio, and ffplay/avplay if not using WAV)\n    # from pydub.playback import play\n    # play(faded_song)\n\nexcept FileNotFoundError:\n    print(\"Error: input.wav not found. Please create one or provide an existing audio file.\")\nexcept Exception as e:\n    print(f\"An error occurred during audio processing: {e}. Check FFmpeg installation if using non-WAV files.\")\n","lang":"python","description":"This quickstart demonstrates how to load an audio file, apply common manipulations like changing volume and adding fade effects, and then export the result to a new file. It includes a fallback to create a dummy WAV file if no input is present, highlighting the dependency on FFmpeg for most real-world formats like MP3."},"warnings":[{"fix":"Install FFmpeg or Libav for your operating system and ensure its `bin` directory is added to your system's PATH. For Windows, you may need to explicitly set `pydub.AudioSegment.converter = '/path/to/ffmpeg.exe'` or `pydub.AudioSegment.ffmpeg = '/path/to/ffmpeg'` if PATH setup is problematic.","message":"Pydub relies heavily on the external command-line tool FFmpeg (or Libav) for handling most audio formats (e.g., MP3, FLAC, OGG, AAC, MP4). Without FFmpeg/Libav installed on your system and its executable directory added to your system's PATH environment variable, Pydub will only be able to process WAV and raw audio files.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always assign the result of an operation to a new variable or reassign it to the original variable, e.g., `song = song + 6` rather than expecting `song` to be modified in-place.","message":"AudioSegment objects in Pydub are immutable. Operations like slicing, changing volume, or applying effects (`+`, `-`, `fade_in()`, `fade_out()`) return a *new* AudioSegment object. The original object remains unchanged.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For playback, install `pip install simpleaudio` (recommended) or `pip install pyaudio`. Alternatively, ensure `ffplay` or `avplay` is available in your system PATH as part of your `ffmpeg`/`libav` installation.","message":"Direct audio playback from Pydub requires additional Python dependencies (like `simpleaudio` or `pyaudio`) or the `ffplay`/`avplay` executable (usually bundled with `ffmpeg`/`libav`) to be installed and accessible.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To debug, enable Pydub's converter logger: \n```python\nimport logging\nl = logging.getLogger(\"pydub.converter\")\nl.setLevel(logging.DEBUG)\nl.addHandler(logging.StreamHandler())\n# Now run your pydub code\n```\nThis will print the exact FFmpeg commands Pydub is executing, helping you identify issues.","message":"When issues arise, especially with converting between formats, the problem is often related to how Pydub interacts with FFmpeg/Libav via subprocess calls.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If adding FFmpeg to PATH doesn't work, you can explicitly tell Pydub where to find the FFmpeg executable by setting `pydub.AudioSegment.converter` or `pydub.AudioSegment.ffmpeg` (depending on Pydub version and context) to the full path of the `ffmpeg.exe` file. Use double backslashes in Windows paths (e.g., `AudioSegment.converter = 'C:\\ffmpeg\\bin\\ffmpeg.exe'`).","message":"On Windows, setting the system PATH for FFmpeg can sometimes be tricky or not fully recognized by Python environments.","severity":"gotcha","affected_versions":"All versions on Windows"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}