linyqh/speclip-skills/ffmpeg-best-practice

FFmpeg Best Practice

Use this skill when the task requires direct FFmpeg work and the answer should be stable, compatible, and easy to adapt.

Scope

• Compression for smaller files without obvious quality loss
• WeChat/mobile/web-safe MP4 output
• Concat, trim, normalize, subtitle burn-in or muxing
• Audio mixing and missing-audio handling
• Hardware encode with software fallback

Core Workflow

1. Probe input files with ffprobe before writing commands.
2. Check encoder availability once per machine/session.
3. Decide whether the job is stream-copy or re-encode.
4. For compression, default to MP4 + H.264 + AAC + yuv420p + +faststart.
5. Prefer capped CRF first; use 2-pass only for a hard file-size target.
6. Use -map 0:a? for optional audio and do not write [0:a?] inside filter_complex.
7. If hardware encode fails or produces oversized output, fall back to libx264.
8. For subtitle burn-in, first collect subtitle style/settings parameters, then convert subtitles to .ass, and only then run burn-in.
9. Return the command, output path, chosen profile, and key flag rationale.

Probe First

Run for each input:

ffprobe -v error -hide_banner -show_streams -show_format -of json "INPUT"

Check once per machine/session:

ffmpeg -hide_banner -encoders
ffmpeg -hide_banner -hwaccels

Minimum checks:

• Video/audio presence
• Resolution, fps, duration, rotation
• Whether target is compatibility-first or strict-size-first
• Available H.264 hardware encoders on this machine

Compression Rules

When the goal is “尽量小，但别太糊”:

1. Do not copy streams. Re-encode.
2. Keep MP4 + H.264 + AAC + yuv420p + +faststart as the default delivery target.
3. Prefer CRF + maxrate + bufsize over pure fixed bitrate.
4. Downscale before crushing bitrate.
5. Clamp fps to 24/25/30 unless higher fps is genuinely needed.
6. Use AAC 64k~96k for speech-heavy output, 96k~128k for general content.
7. Never upscale just to match a target profile.

WeChat-Compatible Core Method

Treat “微信压缩” as a compatibility-first export target, not a claim of exact parity with WeChat’s private pipeline.

• Container: mp4
• Video: H.264, yuv420p
• Audio: AAC-LC, stereo, 44.1kHz or 48kHz
• Delivery: -movflags +faststart
• Frame rate: 24, 25, or 30
• Avoid 10-bit, unusual pixel formats, and fragile containers

Use this ladder as the default starting point:

540p:  CRF 23, maxrate 1000k, bufsize 2000k, AAC 64k~96k
720p:  CRF 22, maxrate 1800k, bufsize 3600k, AAC 96k
1080p: CRF 21, maxrate 2800k, bufsize 5600k, AAC 96k~128k

Selection:

• Short side <= 540: keep at most 540p
• Short side <= 720: keep at most 720p
• Short side > 720: default to 720p; keep 1080p only if detail matters
• Hard upload limit: switch to 2-pass bitrate budgeting

Command Patterns

Replace placeholders like IN, OUT, W, H, FPS, CRF, and bitrate values before running.

1) Fast remux, no compression

ffmpeg -y -i "IN" -map 0:v:0 -map 0:a? -c copy -movflags +faststart "OUT"

2) Web-safe baseline export

ffmpeg -y -i "IN" \
  -c:v libx264 -preset medium -crf 21 -pix_fmt yuv420p \
  -c:a aac -b:a 128k -ar 48000 -ac 2 \
  -map 0:v:0 -map 0:a? -movflags +faststart "OUT"

3) Recommended WeChat-style compression

Default to 720p / 25fps / CRF 22 / maxrate 1800k / bufsize 3600k / AAC 96k unless the source or budget says otherwise.

ffmpeg -y -i "IN" \
  -vf "scale='min(W,iw)':'min(H,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2,pad=W:H:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=FPS" \
  -c:v libx264 -preset slow -crf CRF -maxrate VMAXRATE -bufsize VBUFSIZE \
  -pix_fmt yuv420p -c:a aac -b:a ABITRATE -ar 48000 -ac 2 \
  -map 0:v:0 -map 0:a? -movflags +faststart "OUT"

4) Hard file-size target with 2-pass H.264

target_total_kbps = TARGET_MB * 8192 / DURATION
target_video_kbps = target_total_kbps - audio_kbps - 32

ffmpeg -y -i "IN" \
  -vf "scale='min(W,iw)':'min(H,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2,pad=W:H:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=FPS" \
  -c:v libx264 -preset slow -b:v VBITRATE -maxrate VMAXRATE -bufsize VBUFSIZE \
  -pix_fmt yuv420p -pass 1 -an -f mp4 /dev/null && \
ffmpeg -y -i "IN" \
  -vf "scale='min(W,iw)':'min(H,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2,pad=W:H:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=FPS" \
  -c:v libx264 -preset slow -b:v VBITRATE -maxrate VMAXRATE -bufsize VBUFSIZE \
  -pix_fmt yuv420p -pass 2 -c:a aac -b:a ABITRATE -ar 48000 -ac 2 \
  -map 0:v:0 -map 0:a? -movflags +faststart "OUT"

On Windows, replace /dev/null with NUL.

5) Concat and normalize mixed clips

• Matching streams: use concat demuxer + -c copy
• Mixed sources: re-encode with concat filter after normalizing resolution/fps/audio
• If any clip lacks audio, generate silence first

ffmpeg -y -i "IN" -f lavfi -i anullsrc=channel_layout=stereo:sample_rate=48000 \
  -shortest -map 0:v:0 -map 1:a:0 -c:v copy -c:a aac -b:a 128k "OUT"

6) Subtitle handling

Burn in (required order: get subtitle settings -> convert to ASS -> burn in):

Before any burn-in command, you must first obtain subtitle settings parameters such as:

• font family
• font size
• primary color
• outline/border color and width
• shadow
• alignment/position
• margins / safe area

If subtitle masking is enabled in the current workspace, you must also obtain:

• the exact subtitle mask filter snippet
• the intended visual style of the mask (translucent glass-like blur, not a black rectangle)

Do not burn subtitles directly from raw .srt or other plain subtitle sources. Always convert to .ass first so style and layout are explicit and reproducible.

Required mask-aware burn-in workflow

When the workspace enables subtitle masking, the only correct workflow is:

1. Call subtitle_settings with video_path
2. Read the returned subtitleMaskFilter
3. Convert subtitles to .ass
4. Apply the returned mask filter before the .ass subtitle filter

Rules:

• Use the subtitle_settings mask filter snippet verbatim
• Do not replace it with drawbox, a black rectangle, or a custom gray overlay
• The expected look is a translucent glass-like blur that keeps the background visible while making the source subtitle unreadable
• If the user mentions the preview mask style, treat that preview style as the target appearance
• If the burn-in result visually diverges from the preview, revise the FFmpeg parameters instead of falling back to a dark overlay

Step 1: convert subtitle source to ASS:

ffmpeg -y -i "SUB_INPUT" "SUB.ass"

Step 2: burn in from the generated ASS file:

ffmpeg -y -i "IN" -vf "subtitles='SUB.ass'" \
  -c:v libx264 -preset medium -crf 19 \
  -c:a aac -b:a 128k -map 0:v:0 -map 0:a? -movflags +faststart "OUT"

Mask-aware burn in (preferred when masking is enabled):

ffmpeg -y -i "IN" \
  -filter_complex "SUBTITLE_MASK_FILTER;[masked]subtitles=filename='SUB.ass'[v]" \
  -map "[v]" -map 0:a? \
  -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p \
  -c:a copy -movflags +faststart "OUT"

Notes:

• Replace SUBTITLE_MASK_FILTER with the exact filter string returned by subtitle_settings(video_path=...)
• Do not hand-rewrite that filter unless the user is explicitly debugging the mask effect
• Keep the mask filter and subtitle filter in a single -filter_complex pipeline
• If audio exists and no audio edit is requested, prefer -c:a copy

Soft subtitle mux:

ffmpeg -y -i "IN" -i "SUB.srt" \
  -map 0:v:0 -map 0:a? -map 1:0 \
  -c:v copy -c:a copy -c:s mov_text -movflags +faststart "OUT"

Quick Fallbacks

• matches no streams: replace -map 0:a with -map 0:a?
• Audio labels fail in filter_complex: do not use optional audio labels; pre-create silence
• concat parameter mismatch: pre-normalize clips to the same resolution/fps/audio layout
• Hardware encoder unavailable or output too large: fall back to libx264
• Output still too large: reduce to 720p before increasing CRF
• VFR sync drift: normalize to CFR before audio mixing or concat

Encoder Defaults

• macOS: h264_videotoolbox, fallback libx264
• Windows: h264_nvenc, then h264_qsv, then h264_amf, then libx264
• Best compression efficiency: libx264 -preset slow
• Best compatibility: -pix_fmt yuv420p -movflags +faststart

Output Contract

Always return:

1. Exact command used
2. Output path
3. Chosen profile (copy, web, 540p, 720p, 1080p, or 2-pass)
4. Why key flags were chosen
5. Any fallback applied

Safety

• Never overwrite source media in place
• Prefer absolute output paths
• Probe first when stream topology is uncertain
• Do not claim “exactly WeChat internal compression”; call it compatibility-aligned