{"id":31534011,"url":"https://github.com/othmaneblial/pyffmpegcore","last_synced_at":"2026-05-15T21:01:52.222Z","repository":{"id":316893070,"uuid":"1064849725","full_name":"OthmaneBlial/pyffmpegcore","owner":"OthmaneBlial","description":"A lightweight Python wrapper around FFmpeg/FFprobe for common video/audio processing tasks","archived":false,"fork":false,"pushed_at":"2025-09-27T11:03:37.000Z","size":163,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T12:25:50.401Z","etag":null,"topics":["audio-processing","command-line-tool","ffmpeg","ffmpeg-wrapper","ffprobe","media-conversion","multimedia","python","python-library","video-editing","video-processing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OthmaneBlial.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-26T16:41:59.000Z","updated_at":"2025-09-27T11:09:38.000Z","dependencies_parsed_at":"2025-09-27T12:25:52.931Z","dependency_job_id":"c4176a55-59d6-45a3-83f9-79e78dcf0053","html_url":"https://github.com/OthmaneBlial/pyffmpegcore","commit_stats":null,"previous_names":["othmaneblial/pyffmpegcore"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/OthmaneBlial/pyffmpegcore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmaneBlial%2Fpyffmpegcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmaneBlial%2Fpyffmpegcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmaneBlial%2Fpyffmpegcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmaneBlial%2Fpyffmpegcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OthmaneBlial","download_url":"https://codeload.github.com/OthmaneBlial/pyffmpegcore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmaneBlial%2Fpyffmpegcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278266896,"owners_count":25958733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-processing","command-line-tool","ffmpeg","ffmpeg-wrapper","ffprobe","media-conversion","multimedia","python","python-library","video-editing","video-processing"],"created_at":"2025-10-04T05:16:13.027Z","updated_at":"2026-05-15T21:01:52.214Z","avatar_url":"https://github.com/OthmaneBlial.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyFFmpegCore\n\nA terminal-first media toolkit built on top of `ffmpeg` and `ffprobe`.\n\nUse it when you want to:\n\n- inspect a video or audio file\n- convert video formats\n- compress large videos\n- extract audio from video\n- grab thumbnails\n- generate waveform images\n- join clips together\n- add, extract, or burn subtitles\n- mix or normalize audio\n- batch-convert images\n\n[![PyPI version](https://badge.fury.io/py/pyffmpegcore.svg)](https://pypi.org/project/pyffmpegcore/)\n[![Python versions](https://img.shields.io/pypi/pyversions/pyffmpegcore.svg)](https://pypi.org/project/pyffmpegcore/)\n[![License](https://img.shields.io/pypi/l/pyffmpegcore.svg)](https://pypi.org/project/pyffmpegcore/)\n\n## What This Project Is\n\nPyFFmpegCore is now designed to be used first as a CLI:\n\n```bash\npyffmpegcore ...\n```\n\nIt also still exposes a Python API for developers, but the easiest way to use the project is now the terminal command.\n\n## What Is Verified\n\nAs of March 28, 2026, the repo was validated locally with:\n\n- Python `3.12`\n- `ffmpeg` and `ffprobe` available on `PATH`\n- `105` library and CLI tests\n- real downloaded video, audio, subtitle, and image fixtures\n- end-to-end CLI checks for the shipped commands\n- path handling for spaces and apostrophes in important workflows\n\nThe strongest validation was done on Linux. The repo also now includes installer, packaging, and clean-install checks for the CLI path.\n\n## Install\n\nYou need:\n\n- Python `3.8+`\n- `ffmpeg`\n- `ffprobe`\n\nInstall the CLI with `pipx`:\n\n```bash\npipx install pyffmpegcore\n```\n\nOr with regular `pip`:\n\n```bash\npython -m pip install --user pyffmpegcore\n```\n\nFrom a repo checkout you can also use the one-command installers:\n\n```bash\n./install.sh\n```\n\nWindows uses the PowerShell installer instead:\n\n```powershell\n.\\install.ps1\n```\n\nThen confirm the install:\n\n```bash\npyffmpegcore --version\npyffmpegcore doctor\n```\n\nMore install details are in [CLI_INSTALL.md](CLI_INSTALL.md).\n\n## Five-Minute Start\n\nIf you already have your own files, replace the sample names below with your own.\n\n### 1. Check your setup\n\n```bash\npyffmpegcore doctor\n```\n\n### 2. Inspect a file before changing it\n\n```bash\npyffmpegcore probe --input my-video.mp4\n```\n\n### 3. Convert a WebM or MOV into MP4\n\n```bash\npyffmpegcore convert --input input.webm --output output.mp4 --video-codec libx264 --audio-codec aac\n```\n\n### 4. Make a large video smaller\n\n```bash\npyffmpegcore compress --input large-video.mp4 --output smaller-video.mp4 --crf 28\n```\n\n### 5. Pull the audio out of a video\n\n```bash\npyffmpegcore extract-audio --input interview.mp4 --output interview.mp3\n```\n\n## Practice With The Same Real Files Used In Tests\n\nIf you want safe practice files instead of your own media, download the same fixtures used in real validation:\n\n```bash\npython tests/media/download_fixtures.py\n```\n\nThat creates files under `tests/media/downloads/`.\n\nMain practice files:\n\n| File | What it represents |\n| --- | --- |\n| `tests/media/downloads/sample_mp4_h264.mp4` | a normal MP4 clip with video and audio |\n| `tests/media/downloads/sample_webm_vp9.webm` | a WebM video you want to convert |\n| `tests/media/downloads/sample_video_mov.mov` | a camera or editor export |\n| `tests/media/downloads/sample_audio_mp3.mp3` | a song, podcast, or voice-over clip |\n| `tests/media/downloads/sample_audio_wav.wav` | an uncompressed audio recording |\n| `tests/media/downloads/sample_image_png.png` | a graphic or screenshot |\n| `tests/media/downloads/sample_image_jpg.jpg` | a photo |\n| `tests/media/downloads/sample_subtitles.srt` | a subtitle file you want to attach or burn |\n\n## Copy-Paste Commands\n\n### Inspect a file\n\n```bash\npyffmpegcore probe --input tests/media/downloads/sample_mp4_h264.mp4\npyffmpegcore probe --input tests/media/downloads/sample_mp4_h264.mp4 --json\n```\n\n### Convert WebM to MP4\n\n```bash\npyffmpegcore convert \\\n  --input tests/media/downloads/sample_webm_vp9.webm \\\n  --output converted.mp4 \\\n  --video-codec libx264 \\\n  --audio-codec aac\n```\n\n### Compress a video\n\n```bash\npyffmpegcore compress \\\n  --input tests/media/downloads/sample_mp4_h264.mp4 \\\n  --output compressed.mp4 \\\n  --crf 28\n```\n\n### Extract audio\n\n```bash\npyffmpegcore extract-audio \\\n  --input tests/media/downloads/sample_mp4_h264.mp4 \\\n  --output audio-only.mp3\n```\n\n### Create a thumbnail\n\n```bash\npyffmpegcore thumbnail \\\n  --input tests/media/downloads/sample_mp4_h264.mp4 \\\n  --output thumbnail.jpg \\\n  --timestamp 00:00:01 \\\n  --width 640\n```\n\n### Generate a waveform image\n\n```bash\npyffmpegcore waveform \\\n  --input tests/media/downloads/sample_audio_mp3.mp3 \\\n  --output waveform.png \\\n  --width 1200 \\\n  --height 300\n```\n\n### Burn subtitles into a video\n\n```bash\npyffmpegcore subtitles burn \\\n  --video tests/media/downloads/sample_mp4_h264.mp4 \\\n  --subtitle tests/media/downloads/sample_subtitles.srt \\\n  --output burned-subtitles.mp4\n```\n\n### Join matching clips together\n\n```bash\npyffmpegcore concat \\\n  --inputs tests/media/downloads/sample_mp4_h264.mp4 tests/media/downloads/sample_mp4_h264.mp4 \\\n  --output joined.mp4 \\\n  --mode copy\n```\n\n## Use Your Own Files\n\nReplace the sample paths with your own real filenames:\n\n- `tests/media/downloads/sample_webm_vp9.webm` -\u003e `holiday-video.webm`\n- `tests/media/downloads/sample_mp4_h264.mp4` -\u003e `screen-recording.mp4`\n- `tests/media/downloads/sample_audio_mp3.mp3` -\u003e `podcast-intro.mp3`\n- `tests/media/downloads/sample_subtitles.srt` -\u003e `captions/english.srt`\n\nGood habits:\n\n- put quotes around paths that contain spaces\n- choose the output extension you actually want, like `.mp4`, `.mp3`, `.wav`, `.jpg`, or `.webp`\n- use `pyffmpegcore probe --input your-file` first if you are not sure what kind of file you have\n- open the output file in your normal media player after each command\n\n## Help And Shell Completion\n\nBuilt-in help:\n\n```bash\npyffmpegcore --help\npyffmpegcore convert --help\npyffmpegcore subtitles --help\n```\n\nShell completion:\n\n```bash\npyffmpegcore completion bash\npyffmpegcore completion zsh\npyffmpegcore completion powershell\n```\n\nThe quick command guide is in [CLI_HELP.md](CLI_HELP.md). More task-based examples are in [EXAMPLES.md](EXAMPLES.md).\n\n## Python API\n\nIf you want to call the project from Python code instead of the CLI:\n\n```bash\npython -m pip install pyffmpegcore\n```\n\nExample:\n\n```python\nfrom pyffmpegcore import FFmpegRunner\n\nffmpeg = FFmpegRunner()\nresult = ffmpeg.extract_audio(\"video.mp4\", \"audio.mp3\")\n\nprint(result.returncode)\n```\n\nThe Python API remains useful, but the supported public path is now the `pyffmpegcore` terminal command first.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fothmaneblial%2Fpyffmpegcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fothmaneblial%2Fpyffmpegcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fothmaneblial%2Fpyffmpegcore/lists"}