convert_mux

Description

Rewraps or converts media streams while copying or re-encoding video/audio.
Useful for repairing containers, adjusting codecs, changing formats, resolving sync issues, or preparing files for specific platforms or pipelines.

Purpose

convert_mux is Videobeaux’s advanced container/codec remuxing and transcoding utility.
Compared to the simpler convert program, convert_mux offers:

• deeper codec configuration,
• container formatting,
• bitrate and rate-control management,
• GOP and frame-rate control,
• filter pass-through (vf),
• audio stream shaping,
• curated presets via --profile.

This makes it ideal for delivery specifications, pipeline normalization, or technical media prep.

How It Works

1. Container Selection (--format)
   Determines the output container/muxer hint (mp4, mov, webm, matroska, mxf, gif, image2, avi).
2. Profile-Based Presets (--profile)
   Selecting a profile automatically applies a curated list of FFmpeg flags (codec, pix_fmt, bitrate/quality, audio format, etc.).
3. Manual Codecs and Quality
   If --profile is not used, you can explicitly specify:
   • --vcodec, --acodec,
   • --crf, --bitrate, --maxrate, --bufsize, --preset,
   • --pix-fmt, --gop, -r, --vf, --tagv, etc.
4. Stream Copy Mode
   --copy bypasses re-encoding and performs a container-level remux where streams are compatible.
5. FFmpeg Passthrough
   Extra arguments after -- are passed directly to FFmpeg (ffmpeg_args).
6. Execution
   A command is built and run through run_ffmpeg_with_progress, echoing the FFmpeg command for transparency.

Program Template

videobeaux -P convert_mux \
  -i input.mp4 \
  -o output.mp4 \
  --format VALUE \
  --profile VALUE \
  --vcodec VALUE \
  --acodec VALUE \
  --crf VALUE \
  --bitrate VALUE \
  --maxrate VALUE \
  --bufsize VALUE \
  --preset VALUE \
  --profile-v VALUE \
  --level VALUE \
  --pix-fmt VALUE \
  --gop VALUE \
  -r VALUE \
  --vf VALUE \
  --tagv VALUE \
  --abitrate VALUE \
  --ac VALUE \
  --ar VALUE \
  --copy \
  -- FFMPPEG_ARGS...

Arguments

• format — Force container/muxer hint (mp4, mov, webm, matroska, mxf, gif, image2, avi, etc.).
• profile — Apply a curated preset (see Available Profiles below).
• vcodec — Video codec (e.g., libx264, libx265, libaom-av1, prores_ks, dnxhd, mpeg2video, mpeg4, mjpeg).
• acodec — Audio codec (e.g., aac, libopus, libmp3lame, mp3, pcm_s16le).
• crf — Constant Rate Factor for quality control (lower = higher quality).
• bitrate — Target video bitrate (e.g., 5M).
• maxrate — Maximum video bitrate for rate control.
• bufsize — VBV buffer size to pair with maxrate.
• preset — Codec speed/efficiency preset (e.g., ultrafast, fast, slow).
• profile-v (profile_v) — Video codec profile (e.g., high, main, baseline, or ProRes profile index).
• level — Video level (e.g., 4.1) for device compatibility.
• pix-fmt (pix_fmt) — Pixel format (e.g., yuv420p, yuv422p10le, yuva444p10le).
• gop — GOP/keyframe interval in frames.
• -r — Output frame rate (30000/1001, 25, 24, etc.).
• vf — Video filtergraph string.
• tagv — Force video FourCC/tag (e.g., hvc1).
• abitrate — Audio bitrate (e.g., 192k).
• ac — Audio channel count (e.g., 2).
• ar — Audio sample rate (e.g., 48000).
• copy — When set, stream copy all streams (no re-encode) if compatible.
• ffmpeg_args — Raw arguments after -- passed directly to FFmpeg.

Available Profiles

These are the curated --profile options defined in the code, with their intent:

• mp4_h264
  H.264 in MP4 for general web/delivery.
  • libx264, -preset veryfast, -crf 18, yuv420p, +faststart, AAC 192k stereo.
• mp4_hevc
  HEVC/H.265 in MP4 for higher compression at similar quality.
  • libx265, -preset medium, -crf 22, -tag:v hvc1, yuv420p, +faststart, AAC 192k stereo.
• mp4_av1
  AV1 in MP4 for very efficient modern web delivery.
  • libaom-av1, -crf 28, -b:v 0, yuv420p, +faststart, AAC 192k stereo.
• webm_vp9
  VP9-based WebM for web platforms supporting WebM.
  • libvpx-vp9, -b:v 0, -crf 30, row-mt enabled, yuv420p, Opus 160k stereo.
• webm_av1
  AV1 in WebM with Opus audio.
  • libaom-av1, -crf 32, -b:v 0, yuv420p, Opus 160k stereo.
• prores_422
  ProRes 422 mezzanine for professional workflows.
  • prores_ks, -profile:v 2, yuv422p10le, PCM s16le audio.
• prores_4444
  ProRes 4444 mezzanine with alpha support.
  • prores_ks, -profile:v 4, yuva444p10le, PCM s24le audio.
• dnxhr_hq
  DNxHR HQ mezzanine for Avid / pro pipelines.
  • dnxhd, -profile:v dnxhr_hq, yuv422p, PCM s16le audio.
• mxf_xdcamhd50_1080i59
  Broadcast MXF OP1a XDCAM HD 50, 1080i59.94.
  • mpeg2video at 50M CBR, interlaced, top field first, yuv422p, PCM s24le 48k stereo, -f mxf.
• lossless_ffv1
  FFV1 lossless archival video.
  • ffv1 level 3, intra (g=1), slice CRC, PCM s24le audio.
• gif
  GIF export preset (via palettegen/paletteuse pipeline).
  • Uses fps=15,scale=iw:-2:flags=lanczos in a filter_complex chain.
• png_seq
  PNG image sequence output.
  • -c:v png.
• jpg_seq
  JPEG image sequence output.
  • -qscale:v 2 (high quality JPEG).
• mp3_320
  Audio-only MP3 at 320 kbps.
  • -vn, libmp3lame, -b:a 320k.
• aac_192
  Audio-only AAC at 192 kbps.
  • -vn, aac, -b:a 192k.
• flac
  Audio-only FLAC lossless.
  • -vn, flac.
• avi_mjpeg_fast
  AVI with MJPEG video for fast, edit-friendly intermediates.
  • mjpeg with -q:v 3, PCM s16le audio.
• avi_mpeg4_fast
  AVI with MPEG-4 video tuned for speed.
  • mpeg4, -qscale:v 3, -bf 0, -mbd 0, MP3 192k audio.

Real World Example

videobeaux -P convert_mux \
  -i myvideo.mp4 \
  -o convert_mux_styled.mp4 \
  --format mp4 \
  --profile mp4_h264

Technical Notes

• Profiles apply after basic container inference and can override many manually specified arguments.
• When output ends with .mp4, certain profiles that expect non-MP4 containers (webm_…, mxf_…, gif, etc.) will cause a fail-fast error to avoid confusing FFmpeg errors.
• --copy disables most encoding options and simply remuxes streams when possible.
• GIF and image-sequence profiles bypass typical video/audio handling and use specialized pipelines.
• Additional raw FFmpeg flags can be appended after -- if you need something not exposed via named arguments.

Recommended Usage

• Preparing web deliverables using mp4_h264, mp4_hevc, or mp4_av1.
• Making pro intermediates in prores_422, prores_4444, or dnxhr_hq for editing, grading, or VFX.
• Building broadcast MXF files with mxf_xdcamhd50_1080i59.
• Generating GIFs, PNG/JPEG sequences, or audio-only MP3/AAC/FLAC assets.
• Using --copy to remux without re-encoding when container changes are sufficient.

Quality Tips

• For H.264/H.265, tune CRF and preset if not relying solely on profiles.
• Use the ProRes and DNxHR profiles for grading/VFX workflows where multi-gen quality matters.
• AV1 profiles (mp4_av1, webm_av1) are slower to encode but very efficient for distribution.
• For archival, prefer lossless_ffv1 in Matroska with PCM audio.
• Always inspect container + codec compatibility for your target platform before finalizing a profile.