Communitygithub.com

Upload-Preflight

Prüft eine exportierte Videodatei auf Kompatibilität mit TikTok, YouTube Shorts, Instagram Reels und Facebook Reels und erstellt FFmpeg-Befehle zur Behebung von Fehlern.

Was ist Upload-Preflight?

Mit diesem Skill kannst du überprüfen, ob ein vertikales Video die technischen Anforderungen von TikTok, YouTube Shorts, Instagram Reels und Facebook Reels erfüllt. Er nutzt das Open-Source-Tool shortform-preflight, das auf GitHub gehostet wird, und führt es über npx aus. Das Tool liest die Videodatei mit ffprobe aus und vergleicht die Metadaten (Bildrate, Codec, Auflösung, Länge, Audio-Parameter, Dateigröße, Moov-Atom-Position) mit den von den Plattformen veröffentlichten Spezifikationen. Für jeden festgestellten Fehler wird ein passender FFmpeg-Befehl generiert, um das Problem zu beheben (z.B. Neucodierung, Anpassung der Bildrate, Ändern des Audio-Codecs). Der Skill ist plattformunabhängig und funktioniert auf macOS, Windows und Linux. Er eignet sich für Entwickler, die Videos manuell oder über APIs einreichen, sowie für Content-Ersteller, die sicherstellen wollen, dass ihre Uploads nicht abgelehnt werden. Der Skill gibt klare, tabellarische Ergebnisse aus und zeigt an, welche Regeln (App-Upload, Web-Upload oder API) angewendet wurden. Er vermeidet unnötige Neucodierungen und warnt vor unvollständig veröffentlichten Limits.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/viewgum/skills/tree/HEAD/skills/upload-preflight

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Upload-Preflight (Upload-Vorprüfung)

Ein Render, der gut aussieht, kann trotzdem abgelehnt oder neu verarbeitet werden: die falsche Bildrate für eine API, ein Audio-Codec, den ein Posting-Tool ablehnt, eine Datei über der Größenbeschränkung, ein Clip länger als die App erlaubt. Dieser Skill führt https://github.com/viewgum/shortform-preflight auf der Datei aus, liest sie mit ffprobe aus und prüft sie gegen die von jeder App veröffentlichten Werte und wandelt dann jeden Fehler in einen FFmpeg-Befehl um.

Nicht für: die Position von Text im Bild (dafür gibt es short-form-specs) oder den Inhalt des Videos.

Arbeitsablauf

  1. Umfang nur bei Bedarf klären. Standard: alle vier Apps und die Regeln für das Hochladen in jeder App (--route app). Für den Web-Upload von TikTok --route web verwenden. Wenn der Benutzer über einen Planer oder eigenen Code postet, die Regeln der Publishing-API verwenden (--api), die für Facebook Reels und Instagram strenger sind. Für TikToks Direct Post das Kontolimit (max_video_post_duration_sec aus den TikTok-Entwicklerinformationen) als --tiktok-endpoint direct --tiktok-max-seconds <n> übergeben; ohne dies sagen, dass die Länge unbestätigt ist.
  2. Werkzeuge prüfen: ffprobe -version (FFmpeg), node -v (18 oder neuer) und npx --version. Der erste Run lädt das Prüfprogramm von GitHub herunter, benötigt also auch Netzwerkzugriff. Fehlt etwas, sagen, welches, wie es installiert wird, und anhalten.
  3. Ausführen, als JSON, damit jede Zeile gelesen werden kann: npx -y github:viewgum/shortform-preflight <datei> --json (wenn nötig --api oder --platform tiktok,youtube-shorts anhängen). Exit-Code 0 bedeutet: keine Prüfung fehlgeschlagen; 1 bedeutet: eine Prüfung fehlgeschlagen oder ein erforderlicher Wert konnte nicht gelesen werden (die App wird als unvollständig angezeigt; sagen, welche Messung fehlt); 2 bedeutet: falsche Eingabe.
  4. Für jeden Fehler und jede Warnung, die den Benutzer wahrscheinlich betrifft, die Ursache in einer Zeile, die vom Prüfprogramm zitierte Quelle und eine Korrektur angeben. Übliche Korrekturen (Pfade anpassen, Rest der Datei unverändert lassen):
    • Bildrate außerhalb des Bereichs: ffmpeg -i in.mp4 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a copy -movflags +faststart -use_editlist 0 out.mp4
    • Codec, Chroma oder Profil abgelehnt: ffmpeg -i in.mp4 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart -use_editlist 0 out.mp4
    • Moov-Atom am Ende oder Edit-Liste (Instagram API lehnt beides ab): ffmpeg -i in.mp4 -c copy -movflags +faststart -use_editlist 0 out.mp4
    • Audio-Samplerate, Kanäle oder Bitrate (die Facebook Reels API listet 48 kHz Stereo, 128 kbps oder mehr; ein auf exakt 128k eingestellter Encoder erreicht im Durchschnitt oft etwas weniger): ffmpeg -i in.mp4 -c:v copy -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart -use_editlist 0 out.mp4
    • Zu lang: kürzen, ffmpeg -i in.mp4 -t 89.9 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart -use_editlist 0 out.mp4 (-t etwas unter dem Limit setzen: der Schnitt kann einen Frame länger sein).
    • Mehrere Zeilen gleichzeitig: die Optionen in einer Neucodierung kombinieren, nicht mehrere Durchläufe verketten, wie im Beispiel-Run.
    • Bei jeder Neucodierung: -g 90 bei 30 fps (-g 72 bei 24) hinzufügen, damit Keyframes alle 3 Sekunden kommen; Facebooks API erwartet geschlossene Gruppen von Bildern von 2 bis 5 Sekunden Länge, was das Prüfprogramm nicht testen kann. Prüfen mit ffprobe -v error -select_streams v -skip_frame nokey -show_entries frame=pts_time -of csv=p=0 out.mp4.
    • Zu groß: die Qualitätseinstellung senken (ein höheres -crf) anstatt die Auflösung zu ändern.
    • Nicht 9:16: nur auf 1080 x 1920 zuschneiden oder auffüllen, wenn der Benutzer es wünscht; sagen, was verloren geht.
  5. Nach einer Korrektur das Prüfprogramm erneut auf der neuen Datei ausführen und zeigen, dass die Zeile jetzt bestanden ist.

Ausgabeformat

**Datei:** demo.mp4 · 1080 x 1920 · 95 s · 23.976 fps · H.264 · AAC
**Regeln:** Publishing-APIs

| App | Ergebnis | Fehlgeschlagene oder warnende Zeilen |
|---|---|---|
| Facebook Reels | fail | Länge 95 s (API akzeptiert 3 bis 90 s); Bildrate 23.976 (benötigt 24 bis 60); 44,1 kHz und Mono (48 kHz Stereo gelistet, Warnung) |
| Instagram Reels | fail | Edit-Liste vorhanden (keine erlaubt); Moov-Atom nach den Medien (muss vorne sein) |

### Korrektur
Eine Neucodierung für alle Zeilen: `ffmpeg -i demo.mp4 -t 89.9 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -ar 48000 -ac 2 -g 90 -movflags +faststart -use_editlist 0 fixed.mp4`
(Quellen: Meta for Developers, Reels Publishing API und IG User Media)

**Nach der Korrektur:** keine Fehler.
  • Die eigenen Zeilen des Prüfprogramms zitieren; Limits nicht aus dem Gedächtnis wiederholen.
  • Sagen, welche Regeln verwendet wurden: App-Upload, Web-Upload oder die Publishing-API.
  • Info-Zeilen (empfohlene Bitraten, gemessene Lautstärke) sind keine Fehler; nur erwähnen, wenn der Benutzer fragt.

Häufige Fallstricke

  • Nicht neucodieren, wenn ein Remux es behebt. -c copy mit +faststart erhält die Qualität.
  • Auflösung oder Seitenverhältnis nicht ändern, außer der Benutzer fragt danach; zuerst fragen, weil Zuschneiden Bildverlust bedeutet.
  • Eine Warnung nicht als Ablehnung behandeln. Sagen, was die App tun kann (neu verarbeiten, über API ablehnen) nur so, wie die Quelle es angibt.
  • FFmpeg nicht über die Originaldatei laufen lassen. Immer eine neue Datei schreiben.
  • Kein Limit raten, das das Prüfprogramm als nicht veröffentlicht meldet. Sagen, dass die App es nicht veröffentlicht.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Verwandte Skills