Agent skill

Ffmpeg Graceful Degradation

by HKUDS in HKUDS/OpenSpace

Graceful degradation workflow for ffmpeg encoding failures with progressive fallback strategies

MITAuto-check passedMedia & Creative

Install Ffmpeg Graceful Degradation

skills CLI
$ npx skills add HKUDS/OpenSpace --skill ffmpeg-graceful-degradation -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install HKUDS/OpenSpace ffmpeg-graceful-degradation --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/HKUDS/OpenSpace.git skills-src && mkdir -p .claude/skills && cp -r skills-src/benchmarks/gdpval/skills/ffmpeg-graceful-degradation .claude/skills/ffmpeg-graceful-degradation && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ffmpeg-graceful-degradation
GitHub stars
7.8k
Token cost
~1.6k tokens
SKILL.md length
350 words
Files
2
Skills in repo
199
Repo updated
First seen
Licence
MIT

At a glance

Graceful degradation workflow for ffmpeg encoding failures with progressive fallback strategies

  • Works in 4 steps: Probe Encoder Availability → Test Encoding on Single Short Clip → Progressive Fallback Strategy → …
  • Tasks that involve Video production
  • SKILL.md covers Overview, Step 1: Probe Encoder…, Step 2: Test Encoding on… and Step 3: Progressive Fallback…, plus 5 more sections
  • Calls ffmpeg and pip

What it does

Ffmpeg Graceful Degradation is an agent skill from HKUDS/OpenSpace. Graceful degradation workflow for ffmpeg encoding failures with progressive fallback strategies

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file.

It sits in Media & Creative, covering Video production and Error handling. It works with FFmpeg. The repository describes itself as: "OpenSpace: The Skill Management Layer for AI Agents" -- https://open-space.cloud/. The licence is MIT.

When your agent uses it

  • Tasks that involve Video production
  • Tasks that involve Error handling

Example prompts

  • “/ffmpeg-graceful-degradation”

Requirements

  • Python 3

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Probe Encoder Availability
  2. Test Encoding on Single Short Clip
  3. Progressive Fallback Strategy
  4. Implementation Pattern

What it can do on your machine

Read from SKILL.md and the folder at commit 3827781. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • ffmpeg
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ffmpeg Graceful Degradation loads about 1.6k tokens when it runs. Until then it costs about 31 tokens; SKILL.md has 350 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~31
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from HKUDS/OpenSpace at commit 3827781, republished under its MIT licence (© HKUDS). 350 words, ~1,641 tokens.

Download SKILL.mdSave it as .claude/skills/ffmpeg-graceful-degradation/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
ffmpeg-graceful-degradation
description
Graceful degradation workflow for ffmpeg encoding failures with progressive fallback strategies

FFmpeg Graceful Degradation

When processing videos with ffmpeg, encoding failures are common due to codec availability, library version mismatches, or system configuration issues. This skill provides a systematic fallback strategy to ensure video processing completes successfully.

Overview

The pattern involves: (1) probing encoder availability upfront, (2) testing on a short clip before batch processing, (3) progressive fallback through copy mode, alternative codecs, and finally moviepy, (4) using moviepy as a reliable bundled alternative.

Step 1: Probe Encoder Availability

Before any encoding work, check what encoders are available:

bash
ffmpeg -encoders | grep -E "libx264|libopenh264|mpeg4"

Expected output shows which encoders are present:

  • libx264 - Preferred H.264 encoder (may be missing)
  • libopenh264 - Alternative H.264 (often has library issues)
  • mpeg4 - Universal fallback (always available)

Step 2: Test Encoding on Single Short Clip

Never start batch processing without validation. Extract and test a short segment:

bash
# Extract 5-second test clip
ffmpeg -y -i input.mp4 -ss 0 -t 5 -c copy test_clip.mp4

# Attempt encode with preferred codec
ffmpeg -y -i test_clip.mp4 -c:v libx264 -preset fast test_output.mp4

Check the exit code and output for errors. Common failures:

  • libopenh264.so: wrong ELF class
  • Encoder libx264 not found
  • Library version mismatches

Step 3: Progressive Fallback Strategy

If the preferred encoder fails, try these fallbacks in order:

Fallback A: Copy Mode (No Re-encoding)
bash
ffmpeg -y -i input.mp4 -c:v copy -c:a copy output.mp4

Fast, lossless, but doesn't change codec/format.

Fallback B: MPEG4 Codec
bash
ffmpeg -y -i input.mp4 -c:v mpeg4 -q:v 3 -c:a copy output.mp4

Universal compatibility, larger file sizes, always available.

Fallback C: Install MoviePy (Bundles Working FFmpeg)
bash
pip install moviepy

Then use Python instead of raw ffmpeg:

python
from moviepy.editor import VideoFileClip, concatenate_videoclips

# Single clip processing
clip = VideoFileClip("input.mp4")
clip.write_videofile("output.mp4", codec="libx264")

# Concatenate multiple clips
clips = [VideoFileClip(f) for f in clip_files]
final = concatenate_videoclips(clips)
final.write_videofile("output.mp4", codec="libx264")

MoviePy bundles its own ffmpeg binary, avoiding system library issues.

Show full SKILL.md (134 more words)Show less

Step 4: Implementation Pattern

Here's a complete graceful degradation workflow:

python
import subprocess
import os

def safe_video_encode(input_path, output_path, clips=None):
    """
    Encode video with graceful degradation fallbacks.
    
    Args:
        input_path: Single input file path, or
        clips: List of clip paths for concatenation
    
    Returns:
        True if successful, False otherwise
    """
    
    # Step 1: Check encoder availability
    result = subprocess.run(
        ["ffmpeg", "-encoders"],
        capture_output=True, text=True
    )
    has_libx264 = "libx264" in result.stdout
    has_mpeg4 = "mpeg4" in result.stdout
    
    # Step 2: If concatenating, prepare clips with moviepy
    if clips:
        try:
            from moviepy.editor import VideoFileClip, concatenate_videoclips
            loaded_clips = [VideoFileClip(c) for c in clips]
            final = concatenate_videoclips(loaded_clips)
            final.write_videofile(output_path, codec="libx264", logger=None)
            return True
        except Exception as e:
            print(f"MoviePy failed: {e}")
    
    # Step 3: Try ffmpeg with progressive fallbacks
    encoders_to_try = []
    if has_libx264:
        encoders_to_try.append("libx264")
    encoders_to_try.append("mpeg4")  # Always available
    
    for codec in encoders_to_try:
        cmd = [
            "ffmpeg", "-y",
            "-i", input_path,
            "-c:v", codec,
            "-c:a", "copy",
            output_path
        ]
        result = subprocess.run(cmd, capture_output=True, text=True)
        if result.returncode == 0:
            return True
    
    # Step 4: Last resort - copy mode
    cmd = ["ffmpeg", "-y", "-i", input_path, "-c", "copy", output_path]
    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.returncode == 0

Decision Flow

Start
  │
  ▼
Check encoders (ffmpeg -encoders)
  │
  ├─ libx264 available? ──Yes──► Try libx264
  │         │                       │
  │         No                      └─► Success? ──Yes──► Done
  │         │                                      │
  │         ▼                                      No
  │    Test short clip                             │
  │         │                                      ▼
  │         ▼                               Try -c:v copy
  │    Encode fails? ──Yes──► Check libopenh264    │
  │         │                       │              │
  │         No                      Broken         ▼
  │         │                       │         Try mpeg4
  │         ▼                       ▼              │
  │      Done                  Install moviepy     │
  │                              │                 │
  │                              ▼                 │
  │                         Use VideoFileClip ◄────┘
  │                         concatenate_videoclips
  │                              │
  │                              ▼
  │                            Done
  │
  ▼
End

Key Principles

  1. Test first, batch later - Always validate on a short clip
  2. Fail fast, fallback gracefully - Don't waste time on doomed encodings
  3. MoviePy as safety net - Its bundled ffmpeg avoids system issues
  4. Copy mode preserves content - Even if quality isn't ideal

Common Error Patterns

Error MessageCauseSolution
libopenh264.so: wrong ELF classLibrary architecture mismatchUse moviepy or mpeg4
Encoder libx264 not foundFFmpeg built without x264Use mpeg4 fallback
Broken pipeProcess killed mid-operationTry copy mode first
Invalid data foundCorrupt or incompatible inputRe-extract source

When to Use This Skill

  • Processing user-uploaded videos (unknown codecs/formats)
  • Running in containers with limited codec support
  • Batch processing where failure would be costly
  • Cross-platform deployments with varying ffmpeg builds

© HKUDS, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in benchmarks/gdpval/skills/ffmpeg-graceful-degradation of HKUDS/OpenSpace.

  • SKILL.md
  • .skill_id

Open the folder on GitHubat commit 3827781

Compare with similar skills

Ffmpeg Graceful Degradation next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ffmpeg Graceful Degradation compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ffmpeg Graceful Degradation this skillHKUDS/OpenSpace7.8k—~1.6kAutomated safety check: PassMIT
Video Understandcalesthio/OpenMontage66k—~841Automated safety check: PassAGPL-3.0
HyperFrames Video Entry Pointheygen-com/hyperframes60k3 repos~5.2kAutomated safety check: PassApache-2.0
Video Shotseternityspring/reelbench-skills8781 repos~1.8kAutomated safety check: NotesApache-2.0
Mobile Demo Film Editorsuperset-sh/superset15k—~1.8kAutomated safety check: PassCustom licence
Video Editcalesthio/OpenMontage66k—~855Automated safety check: NotesAGPL-3.0

Similar skills

  • Video Understand

    calesthio/OpenMontage

    Understand video content locally using ffmpeg frame extraction and Whisper transcription.

    66k GitHub stars~841 tokensUpdated 7 days ago
    Media & CreativeAuto-check passed
  • HyperFrames Video Entry Point

    heygen-com/hyperframes

    Entry point for making, editing and rendering videos from HTML compositions with HyperFrames, routing each request to the right workflow.

    60k GitHub starsUsed in 3 repos~5.2k tokens
    Media & CreativeAuto-check passed
  • Video Shots

    eternityspring/reelbench-skills

    拉片:把一条成片拆成逐镜头的分析表——每个镜头的时长、景别、类别、运镜、画面. An agent skill from eternityspring/reelbench-skills.

    878 GitHub starsUsed in 1 repo~1.8k tokens
    Media & CreativeAuto-check: notes
  • Mobile Demo Film Editor

    superset-sh/superset

    Edits real mobile screen recordings into a configurable demo video with phone framing, title cards, cutaways and an end card, using a bundled renderer.

    15k GitHub stars~1.8k tokensUpdated yesterday
    Media & CreativeAuto-check passed
  • Video Edit

    calesthio/OpenMontage

    Edit videos locally using ffmpeg. An agent skill from calesthio/OpenMontage.

    66k GitHub stars~855 tokensUpdated 7 days ago
    Media & CreativeAuto-check: notes
  • Lemo-Opuscar Short Film Director

    lemomo-ai/lemo-opuscar

    Directs a short film made entirely in code in one of the Lemo-Opuscar library's named visual styles, from fetching the library through production and delivery.

    1.7k GitHub stars~596 tokensUpdated yesterday
    Media & CreativeAuto-check passed

More from HKUDS/OpenSpace

All 199 skills in this repo
  • Walks through producing a master audio track plus stems in Python, from checking a reference file and timing sections by BPM to effects, a zip archive and final verification.

    7.8k GitHub stars~2.9k tokensUpdated 1 mo ago
    Auto-check passed
  • Handle cascading data retrieval tool failures by falling back to embedded knowledge generation

    7.8k GitHub stars~765 tokensUpdated 1 mo ago
    Auto-check passed
  • Gives an agent a workaround when its code-execution sandbox keeps failing: save the Python script to a file and run it through the shell instead.

    7.8k GitHub stars~588 tokensUpdated 1 mo ago
    Auto-check passed
  • A recovery routine for agents whose sandboxed code runner keeps failing: save the Python script to disk, then run it through the shell and read the output.

    7.8k GitHub stars~652 tokensUpdated 1 mo ago
    Auto-check passed
  • Fallback ladder for failed sandboxed code runs, plus the habit of fixing the working directory first so generated files land in the right place.

    7.8k GitHub stars~1.1k tokensUpdated 1 mo ago
    Auto-check passed
  • Fallback workflow for executing Python code when executecodesandbox fails repeatedly

    7.8k GitHub stars~1.1k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Questions about Ffmpeg Graceful Degradation

What does Ffmpeg Graceful Degradation do?

Graceful degradation workflow for ffmpeg encoding failures with progressive fallback strategies. Ffmpeg Graceful Degradation is an agent skill from HKUDS/OpenSpace.

When should I use Ffmpeg Graceful Degradation?

Ffmpeg Graceful Degradation fits situations like: tasks that involve Video production; tasks that involve Error handling.

How do I install Ffmpeg Graceful Degradation in Claude Code?

Run `npx skills add HKUDS/OpenSpace --skill ffmpeg-graceful-degradation -a claude-code`. Or copy the skill folder (benchmarks/gdpval/skills/ffmpeg-graceful-degradation in HKUDS/OpenSpace) into .claude/skills/ffmpeg-graceful-degradation in your project. Claude Code loads it when a task matches its description.

How do I install Ffmpeg Graceful Degradation in Codex?

Run `npx skills add HKUDS/OpenSpace --skill ffmpeg-graceful-degradation -a codex`. Or copy the skill folder (benchmarks/gdpval/skills/ffmpeg-graceful-degradation in HKUDS/OpenSpace) into .agents/skills/ffmpeg-graceful-degradation in your project. Codex loads it when a task matches its description.

Can I use Ffmpeg Graceful Degradation in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add HKUDS/OpenSpace --skill ffmpeg-graceful-degradation -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ffmpeg-graceful-degradation, .gemini/skills/ffmpeg-graceful-degradation, .github/skills/ffmpeg-graceful-degradation and .opencode/skills/ffmpeg-graceful-degradation in your project.

What does Ffmpeg Graceful Degradation need to run?

Going by SKILL.md and its folder, Ffmpeg Graceful Degradation needs the command-line tools its instructions call (ffmpeg and pip). Our summary lists: Python 3.

Does Ffmpeg Graceful Degradation access the network?

SKILL.md contains no URLs. Its commands use pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Ffmpeg Graceful Degradation safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Ffmpeg Graceful Degradation use?

Ffmpeg Graceful Degradation is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ffmpeg Graceful Degradation use?

About 1.6k tokens (SKILL.md is roughly 6.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ffmpeg Graceful Degradation?

Skills that share tags, products or a category with Ffmpeg Graceful Degradation: Video Understand (calesthio/OpenMontage, 66k stars), HyperFrames Video Entry Point (heygen-com/hyperframes, 60k stars), Video Shots (eternityspring/reelbench-skills, 878 stars) and Mobile Demo Film Editor (superset-sh/superset, 15k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ffmpeg Graceful Degradation?

HKUDS (a GitHub organization) maintains it in HKUDS/OpenSpace, which has 7,754 GitHub stars. The repository holds 199 skills in this directory. The repository was last updated on August 12, 2026.

Source: HKUDS/OpenSpace on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.