{"id":1831,"library":"ffmpy","title":"FFmpy","description":"ffmpy is a simple Python wrapper for FFmpeg, allowing execution of FFmpeg commands from Python. It's designed for straightforward use cases rather than full feature parity with FFmpeg's extensive options. The current version is 1.0.0, released after a significant rewrite, marking an infrequent but active development cadence.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/jbouse/ffmpy","tags":["ffmpeg","video","audio","media","wrapper","cli"],"install":[{"cmd":"pip install ffmpy","lang":"bash","label":"Install ffmpy"}],"dependencies":[],"imports":[{"note":"The primary class was renamed from `FFMPEG` to `FFmpeg` in version 1.0.0.","wrong":"from ffmpy import FFMPEG","symbol":"FFmpeg","correct":"from ffmpy import FFmpeg"}],"quickstart":{"code":"import os\nimport struct\nfrom ffmpy import FFmpeg, FFExecutableNotFoundError, FFRuntimeError\n\ndummy_input_path = \"dummy_input.wav\"\ndummy_output_path = \"dummy_output.mp3\"\n\ntry:\n    # Create a dummy 1-second 8kHz mono 8-bit silent WAV file\n    # RIFF header\n    chunk_id = b'RIFF'\n    chunk_size = 36 + 8000 # Header (36) + data (8000 samples * 1 byte/sample)\n    format_str = b'WAVE'\n\n    # FMT sub-chunk\n    subchunk1_id = b'fmt '\n    subchunk1_size = 16\n    audio_format = 1 # PCM\n    num_channels = 1 # Mono\n    sample_rate = 8000\n    byte_rate = sample_rate * num_channels * 1 # 8000 * 1 * 1\n    block_align = num_channels * 1 # 1 * 1\n    bits_per_sample = 8\n\n    # DATA sub-chunk\n    subchunk2_id = b'data'\n    subchunk2_size = 8000 # 1 second of 8-bit 8kHz mono\n\n    with open(dummy_input_path, 'wb') as f:\n        f.write(chunk_id)\n        f.write(struct.pack('<I', chunk_size))\n        f.write(format_str)\n        f.write(subchunk1_id)\n        f.write(struct.pack('<I', subchunk1_size))\n        f.write(struct.pack('<H', audio_format))\n        f.write(struct.pack('<H', num_channels))\n        f.write(struct.pack('<I', sample_rate))\n        f.write(struct.pack('<I', byte_rate))\n        f.write(struct.pack('<H', block_align))\n        f.write(struct.pack('<H', bits_per_sample))\n        f.write(subchunk2_id)\n        f.write(struct.pack('<I', subchunk2_size))\n        f.write(b'\\x80' * subchunk2_size) # 8-bit unsigned silence is 0x80 (128)\n\n    ff = FFmpeg(\n        inputs={dummy_input_path: None},\n        outputs={dummy_output_path: '-codec:a libmp3lame -q:a 2'}\n    )\n    print(f\"Executing FFmpeg command: {ff.cmd}\")\n    ff.run()\n    print(f\"Successfully converted '{dummy_input_path}' to '{dummy_output_path}'\")\n\nexcept FFExecutableNotFoundError:\n    print(\"Error: FFmpeg executable not found. Please ensure FFmpeg is installed and in your system's PATH.\")\nexcept FFRuntimeError as e:\n    print(f\"Error during FFmpeg execution. Exit code: {e.exit_code}\")\n    print(f\"FFmpeg stderr: {e.stderr.decode('utf-8')}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if os.path.exists(dummy_input_path):\n        os.remove(dummy_input_path)\n    if os.path.exists(dummy_output_path):\n        os.remove(dummy_output_path)\n    print(\"Cleaned up dummy files.\")","lang":"python","description":"This example demonstrates how to convert a dummy WAV file to MP3 using ffmpy. It includes creating a temporary input file, executing the FFmpeg command, and basic error handling, along with cleanup."},"warnings":[{"fix":"Install FFmpeg on your operating system (e.g., via Homebrew on macOS, apt on Debian/Ubuntu, or downloading binaries).","message":"ffmpy is a wrapper around the FFmpeg executable, not a pure Python implementation. You must have FFmpeg installed on your system and available in your system's PATH for ffmpy to function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the new `FFmpeg` class constructor and method signatures. Update imports and method calls to match the 1.0.0 API.","message":"Version 1.0.0 represents a significant rewrite. Key changes include renaming the main class from `FFMPEG` to `FFmpeg`, and substantial modifications to the constructor signature and method interfaces. Code written for 0.x versions will not work with 1.0.0 without adaptation.","severity":"breaking","affected_versions":">=1.0.0 (when migrating from <1.0.0)"},{"fix":"Pass FFmpeg options as a string value associated with each input/output file key, e.g., `outputs={'output.mp4': '-c:v libx264 -preset medium'}`.","message":"FFmpeg options are typically passed as a single string per input/output file in the `inputs` and `outputs` dictionaries. It does not accept a global list or string of options, which is a common mistake for users familiar with `ffmpeg-python` or complex CLI usage.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust expectations based on the library's scope. For advanced or highly customized FFmpeg operations, consider `ffmpeg-python` or direct subprocess calls.","message":"ffmpy is designed as a 'simple' wrapper. It offers a direct way to run FFmpeg commands but does not aim to expose all of FFmpeg's vast feature set or provide deep programmatic control over every parameter like more complex wrappers (e.g., `ffmpeg-python`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}