Communitygithub.com

업로드 사전 점검

사용자가 세로 동영상을 렌더링하거나 내보낸 후, TikTok, YouTube Shorts, Instagram Reels 또는 Facebook Reels에서 해당 동영상을 수락할지, 혹은 업로드나 예약 게시가 실패한 이유를 확인할 때 사용합니다. ffprobe로 게시된 검사기를 실행하고 각 실패에 대한 FFmpeg 수정 명령을 제공합니다.

업로드 사전 점검란 무엇인가요?

이 스킬은 세로형 쇼트폼 동영상이 주요 소셜 플랫폼(TikTok, YouTube Shorts, Instagram Reels, Facebook Reels)의 업로드 요구 사항을 충족하는지 사전에 검증하는 도구입니다. `shortform-preflight`라는 GitHub 기반 검사기를 `npx`로 실행하며, FFmpeg의 `ffprobe`를 사용해 동영상 파일의 프레임 레이트, 코덱, 해상도, 길이, 오디오 설정 등 기술적 세부 정보를 추출합니다. 추출된 정보를 각 플랫폼이 공식적으로 발표한 업로드 규격(앱 업로드, 웹 업로드, 게시 API 등)과 비교하여 문제가 있는 항목을 JSON 형식으로 보고하고, 각 문제를 해결할 수 있는 구체적인 FFmpeg 명령어를 제공합니다. 개발자와 콘텐츠 제작자가 업로드 실패 원인을 빠르게 진단하고, 원본 파일을 보존하면서도 규격에 맞게 변환할 수 있도록 지원합니다. 여러 문제를 한 번에 해결하는 단일 재인코딩 명령을 제안함으로써 작업 효율성을 높이고, 사용자가 직접 제한 값을 기억하지 않아도 되도록 검사기의 공식 데이터를 인용하여 신뢰성을 유지합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/viewgum/skills/tree/HEAD/skills/upload-preflight

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

업로드 사전 점검은(는) 무엇을 하나요?

멀쩡해 보이는 렌더링 결과물도 거부되거나 재처리될 수 있습니다: API가 허용하지 않는 프레임 레이트, 게시 도구가 거부하는 오디오 코덱, 파일 크기 제한 초과, 앱이 처리할 수 있는 시간보다 긴 클립 등이 원인입니다. 이 스킬은 https://github.com/viewgum/shortform-preflight 를 파일에 대해 실행합니다. 이 검사기는 ffprobe로 파일을 읽고 각 앱에서 공개한 수치와 비교한 후, 모든 실패 항목을 하나의 FFmpeg 명령으로 변환합니다.

다음에는 사용하지 않음: 프레임 내 텍스트 위치 (대신 short-form-specs 사용), 동영상의 내용.

워크플로우

  1. 필요한 경우에만 범위를 명확히 합니다. 기본값: 네 앱 모두, 각 앱의 업로드 규칙 (--route app). TikTok 웹 업로드는 --route web을 사용합니다. 사용자가 스케줄러나 자체 코드를 통해 게시하는 경우 게시 API 규칙 (--api)을 사용하며, Facebook Reels와 Instagram의 경우 더 엄격합니다. TikTok Direct Post의 경우, 계정 한도 (TikTok 크리에이터 정보의 max_video_post_duration_sec)를 --tiktok-endpoint direct --tiktok-max-seconds <n>으로 전달하고, 없으면 길이가 확인되지 않았다고 말합니다.
  2. 도구 확인: ffprobe -version (FFmpeg), node -v (18 이상) 및 npx --version. 첫 번째 실행은 GitHub에서 검사기를 다운로드하므로 네트워크 액세스도 필요합니다. 누락된 것이 있으면 무엇인지, 설치 방법을 알려주고 중단합니다.
  3. JSON 형식으로 실행하여 모든 행을 읽을 수 있도록 합니다: npx -y github:viewgum/shortform-preflight <file> --json (필요에 따라 --api 또는 --platform tiktok,youtube-shorts 추가). 종료 코드 0은 검사 실패 없음; 1은 검사 실패 또는 필요한 수치를 읽을 수 없음 (앱이 불완전하게 표시됨; 누락된 측정값을 알려줌); 2는 잘못된 입력.
  4. 각 실패에 대해, 그리고 사용자가 직면할 가능성이 있는 각 경고에 대해, 한 줄로 원인, 행이 인용한 출처, 그리고 하나의 수정 명령을 제공합니다. 일반적인 수정 명령 (경로를 조정하고 파일의 나머지 부분은 유지):
    • 프레임 레이트 범위 초과: ffmpeg -i in.mp4 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a copy -movflags +faststart -use_editlist 0 out.mp4
    • 코덱, 크로마 또는 프로필 거부: 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이 끝에 있거나 edit list 존재 (Instagram API는 둘 다 거부): ffmpeg -i in.mp4 -c copy -movflags +faststart -use_editlist 0 out.mp4
    • 오디오 샘플 레이트, 채널 또는 비트레이트 (Facebook Reels API는 48kHz 스테레오, 128kbps 이상을 명시; 정확히 128k로 설정된 인코더는 종종 평균이 약간 낮음): ffmpeg -i in.mp4 -c:v copy -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart -use_editlist 0 out.mp4
    • 너무 긴 경우: 자르기, 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를 한도보다 약간 작게 설정: 자르기가 한 프레임 길어질 수 있음).
    • 여러 행이 동시에 발생하는 경우: 패스를 체이닝하지 말고 하나의 재인코딩에 옵션을 결합합니다 (예제 실행 참조).
    • 모든 재인코딩: 30fps에서는 -g 90 추가 (24fps에서는 -g 72)로 키프레임이 3초마다 오도록 합니다. Facebook API는 2~5초 길이의 닫힌 GOP 그룹을 요구하지만, 검사기는 이를 테스트할 수 없습니다. 다음 명령으로 확인: ffprobe -v error -select_streams v -skip_frame nokey -show_entries frame=pts_time -of csv=p=0 out.mp4.
    • 너무 큰 경우: 해상도보다는 품질 설정 (-crf를 높임)을 낮춥니다.
    • 9:16이 아닌 경우: 사용자가 원하는 경우에만 1080 x 1920으로 패딩 또는 크롭하고, 손실될 내용을 알려줍니다.
  5. 수정 후 새 파일에 대해 검사기를 다시 실행하고 해당 행이 이제 통과함을 보여줍니다.

출력 형식

**파일:** demo.mp4 · 1080 x 1920 · 95 s · 23.976 fps · H.264 · AAC
**규칙:** 게시 API

| 앱 | 결과 | 실패 또는 경고 행 |
|---|---|---|
| Facebook Reels | 실패 | 길이 95초 (API는 3~90초 허용); 프레임 레이트 23.976 (24~60 필요); 44.1kHz 및 모노 (48kHz 스테레오 명시됨, 경고) |
| Instagram Reels | 실패 | edit list 존재 (허용되지 않음); moov atom이 미디어 뒤에 있음 (앞에 있어야 함) |

### 수정
모든 행에 대한 하나의 재인코딩: `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`
(출처: Meta for Developers, Reels 게시 API 및 IG User Media)

**수정 후:** 실패 없음.
  • 검사기 자체 행을 인용하고, 기억에서 제한 값을 다시 말하지 마십시오.
  • 사용된 규칙을 명시하십시오: 앱 업로드, 웹 업로드 또는 게시 API.
  • 정보 행 (권장 비트레이트, 측정된 음량)은 실패가 아닙니다. 사용자가 요청하는 경우에만 언급하십시오.

일반적인 함정

  • 리먹스로 해결되는 경우 재인코딩하지 마십시오. -c copy와 +faststart로 품질을 유지합니다.
  • 사용자가 요청하지 않는 한 해상도나 종횡비를 변경하지 마십시오. 먼저 물어보십시오. 크롭은 화면을 잃기 때문입니다.
  • 경고를 거부로 처리하지 마십시오. 앱이 할 수 있는 동작 (재처리, API를 통한 거부)은 출처가 명시한 대로만 말하십시오.
  • 원본 파일에 대해 FFmpeg를 실행하지 마십시오. 항상 새 파일을 작성하십시오.
  • 검사기가 게시되지 않았다고 보고하는 한도를 추측하지 마십시오. 앱이 게시하지 않는다고 말하십시오.

Individual skills in this repo

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

관련 스킬