x-video-download-normalization

X Video Download Normalization

Use this for X/Twitter video downloads when consistency matters more than preserving source filenames.

Workflow

1. Save all X video downloads under one shared directory:
   • ~/.Hermes/workspace/output/x_videos/
2. Derive a generic filename from the account handle and tweet/status ID:
   • x_video_<handle>_<statusid>.mp4
3. Download with yt-dlp into a temp subfolder first.
4. If the downloaded container is already .mp4, move it into place.
5. If it is not .mp4, convert it to mp4 with ffmpeg:
   • video: libx264
   • audio: aac
6. Remove the temp folder.
7. Verify the result with:
   • ls -lh
   • ffprobe -show_entries format=duration,size:stream=codec_name,width,height -of json

Commands

Single X status URL

BASE="$HOME/.Hermes/workspace/output/x_videos"
TMP="$BASE/.tmp_<handle>_<statusid>"
mkdir -p "$TMP"
yt-dlp --no-playlist -o "$TMP/%(uploader)s_%(id)s.%(ext)s" "<x-url>"
RAW=$(find "$TMP" -maxdepth 1 -type f | head -1)
DEST="$BASE/x_video_<handle>_<statusid>.mp4"
EXT="${RAW##*.}"
if [ "$EXT" = "mp4" ]; then
  mv -f "$RAW" "$DEST"
else
  ffmpeg -y -i "$RAW" -c:v libx264 -c:a aac "$DEST"
fi
rm -rf "$TMP"

Verification

ls -lh "$DEST"
ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height -of json "$DEST"

Important notes

• Prefer --no-playlist for X URLs that include /video/1 or when yt-dlp tries to treat the post as a playlist.
• X status URLs may resolve internally to a different media item ID during download; preserve the user-facing status ID in the output filename anyway.
• Always report back the final saved path, duration, size, resolution, and codecs when available.
• Keep filenames generic and stable; do not reuse the long source title as the final local filename.

Pitfall: Slow HLS fragment downloads for large X videos

Some X/Twitter videos — especially long ones (30min+, 200MB+) — use HLS streaming with thousands of small fragments (e.g., 3386 fragments for a 450MB file). The default yt-dlp behavior downloads all fragments sequentially, which can take 20+ minutes on typical connections and is prone to timeout.