{"id":6048,"library":"pydub-stubs","title":"pydub-stubs","description":"pydub-stubs is a stub-only package providing type information for the pydub library. It aims to enhance type checking and IDE support for pydub, covering its public interface and some private functions. The package is actively maintained, with versions generally aligning with the pydub releases.","status":"active","version":"0.25.1.6","language":"en","source_language":"en","source_url":"https://github.com/clo4/pydub-stubs","tags":["audio","typing","stubs","pydub","type-checking"],"install":[{"cmd":"pip install pydub-stubs","lang":"bash","label":"Install pydub-stubs"}],"dependencies":[{"reason":"This package provides type information for the pydub library, which must be installed for runtime functionality.","package":"pydub","optional":false},{"reason":"Required by pydub for handling non-WAV audio formats (e.g., MP3, FLAC) and many audio operations. This is a system-level dependency, not a Python package.","package":"ffmpeg","optional":true}],"imports":[{"symbol":"AudioSegment","correct":"from pydub import AudioSegment"},{"symbol":"play","correct":"from pydub.playback import play"},{"note":"Some effect functions are dynamically added to AudioSegment at runtime and may not be directly importable from pydub.","wrong":"from pydub import effects","symbol":"effects","correct":"import pydub.effects"}],"quickstart":{"code":"from pydub import AudioSegment\nfrom pydub.playback import play\nimport os\n\n# Create a dummy silent WAV file for demonstration\nsilent_audio = AudioSegment.silent(duration=1000) # 1 second of silence\nsilent_audio.export(\"input.wav\", format=\"wav\")\n\n# Load an audio file (replace with your actual file if not using dummy)\nsong = AudioSegment.from_file(\"input.wav\", format=\"wav\")\n\n# Boost volume by 6 dB\nlouder_song = song + 6\n\n# Export the modified audio\nlouder_song.export(\"output.wav\", format=\"wav\")\n\n# Play the original and louder song (requires simpleaudio or similar for playback)\n# print(\"Playing original song...\")\n# play(song)\n# print(\"Playing louder song...\")\n# play(louder_song)\n\nprint(\"Original and louder audio files created as input.wav and output.wav\")\nprint(\"Note: For non-WAV formats (like MP3), pydub requires ffmpeg or libav to be installed and in your system PATH.\")\n\n# Clean up dummy files\nos.remove(\"input.wav\")\nos.remove(\"output.wav\")","lang":"python","description":"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."},"warnings":[{"fix":"Install FFmpeg or libav from their official sources and add their binary directory to your system's PATH environment variable.","message":"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.","severity":"gotcha","affected_versions":"All pydub versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All pydub-stubs 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.","message":"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.","severity":"deprecated","affected_versions":"pydub-stubs <= 0.25.1.6 (and corresponding pydub versions)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All pydub-stubs versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All pydub versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}