터미널 기술로 AI 비디오 업로드를 지루할 정도로 단순하게 만드는 방법

AI 비디오 데모를 생성하는 것은 점점 쉬워지고 있습니다.

하지만 이를 게시하는 것은 여전히 이상할 정도로 불안정합니다.

지난주에 저는 간단한 작업을 수행해야 했습니다. AI로 생성된 데모 비디오를 가져와서 포스트에 첨부하고, 플랫폼이 미디어를 조용히 누락시키지 않도록 게시하는 것이었습니다.

로컬 환경에서 비디오는 멀쩡해 보였습니다.

하지만 업로드는 그렇지 않았습니다.

잘못된 코덱 (Codec). 너무 큰 용량. 느린 처리 속도. 미리보기 누락. 명확한 에러 메시지 없음. 브라우저는 업로드가 성공했다고 말했지만, 작성기 (Composer)는 실제로 파일을 등록하지 않았습니다.

이것은 제가 밤 11시에 기억에만 의존해서 해결하고 싶지 않은 종류의 문제입니다.

그래서 저는 이것을 하나의 터미널 기술 (Terminal Skill)로 만들었습니다.

거대한 자동화 플랫폼도 아니고, 마법 같은 에이전트 프롬프트 (Agent prompt)도 아닙니다. 그저 엉망인 비디오 파일을 가져와서 변환 전후의 체크 과정을 거쳐 X(구 Twitter)에 안전한 기본 MP4 파일을 생성하는, 작고 반복 가능한 워크플로우 (Workflow)일 뿐입니다.

사용 사례는 다음과 같습니다.

실제 문제

AI 비디오 도구들은 기술적으로는 유효하지만 소셜 플랫폼에서는 다루기 까다로운 파일들을 자주 내보냅니다.

흔한 문제들:

• 파일 용량이 너무 큼
• 코덱 (Codec)이 QuickTime에서는 허용되지만 플랫폼에서는 허용되지 않음
• 픽셀 포맷 (Pixel format)이 yuv420p가 아님
• 메타데이터 (Metadata)가 웹 재생에 최적화되지 않음
• 해상도 (Resolution)가 필요 이상으로 높음
• 오디오 트랙이 누락되었거나 이상함
• 시각적으로 길이는 괜찮지만 플랫폼 처리 과정에서 멈춤

FFmpeg를 사용하면 이 문제의 대부분을 해결할 수 있습니다.

하지만 문제는 FFmpeg의 존재를 아느냐가 아닙니다.

문제는 정확한 플래그 (Flags)를 기억하고, 이를 일관되게 실행하며, 출력을 확인하고, 플랫폼이 실제 미리보기를 보여줄 때까지 브라우저 업로드를 신뢰하지 않는 것입니다.

이 지점에서 터미널 기술 (Terminal Skill)이 도움이 됩니다.

터미널 기술이란 무엇을 의미하는가

이 워크플로우 (Workflow)를 위한 터미널 기술은 다음과 같은 요소가 담긴 작은 폴더입니다:

• 변환을 수행하는 하나의 스크립트 (Script)
• 변환 전의 하나의 검증 단계
• 변환 후의 하나의 검증 단계
• 언제 사용하는지 설명하는 짧은 SKILL.md 파일
• 예측 가능한 입력 및 출력 경로
• 무엇이 일어났는지 명확하게 보여주는 로그 (Logs)

중요한 부분은 스크립트 그 자체가 아닙니다.

중요한 점은 매번 규칙을 새로 발견할 필요 없이 사람이나 에이전트(Agent)가 워크플로우(Workflow)를 재사용할 수 있게 된다는 것입니다.

이 기술(Skill)은 다음 질문들에 답을 제공합니다:

언제 이것을 사용해야 하는가?
어떤 입력을 기대하는가?
어떤 출력을 생성해야 하는가?
...

마지막 질문이 매우 중요합니다.

외부 플랫폼의 경우, "명령어가 성공했다"는 것이 "게시물이 게시하기에 안전하다"는 것과 동일하지는 않기 때문입니다.

폴더 구조

저는 구조를 지루할 정도로 단순하게 유지했습니다:

x-safe-video/
  SKILL.md
  make-x-safe.sh
...

스크립트는 기계적인 작업을 수행합니다.

SKILL.md는 운영 규칙을 문서화합니다:

# X-Safe Video

X/Twitter 업로드를 위해 생성된 비디오를 준비할 때 사용하십시오.
...

이것이 스크립트(Script)와 기술(Skill)의 차이입니다.

스크립트는 다음과 같이 말합니다:

이 명령어를 실행하세요.

기술은 다음과 같이 말합니다:

여기 워크플로우(Workflow), 경계(Boundary), 그리고 완료의 정의(Definition of Done)가 있습니다.

변환 스크립트

단순화된 버전은 다음과 같습니다.

#!/usr/bin/env bash
set -euo pipefail

...

이것은 세상에서 가장 진보된 FFmpeg 명령어는 아닙니다.

그게 핵심입니다.

목표는 가장 영리한 미디어 파이프라인(Media Pipeline)을 만드는 것이 아닙니다. 목표는 압박 속에서도 작동하는 신뢰할 수 있는 기본값(Default)을 만드는 것입니다.

이 플래그(Flags)들이 중요한 이유

중요한 부분들입니다:

-c:v libx264

H.264는 여전히 소셜 미디어 업로드를 위한 가장 안전한 기본값입니다.

-pix_fmt yuv420p

이는 픽셀 포맷(Pixel Format)과 관련하여 발생하는 전형적인 "로컬에서는 작동하지만 다른 곳에서는 실패하는" 문제를 방지합니다.

-movflags +faststart

이는 메타데이터를 파일의 시작 부분으로 이동시켜 웹 재생이 더 빠르게 시작될 수 있도록 합니다.

-vf "scale='min(1280,iw)':-2"

이는 작은 비디오는 변경하지 않고, 크기가 너무 큰 비디오는 실용적인 너비로 축소합니다.

-crf 23

거대한 파일 용량을 만들지 않으면서도 충분히 좋은 품질을 제공합니다.

비디오마다 이를 튜닝할 수 있냐고요? 네, 가능합니다.

하지만 20초짜리 AI 데모를 게시할 때마다 매번 그 생각을 하고 싶냐고요? 아니요.

검증 단계가 진짜 기술이다

변환은 워크플로우의 절반일 뿐입니다.

플랫폼 체크(Platform Check)가 더 중요합니다.

저의 현재 규칙은 다음과 같습니다:

"업로드 성공"을 믿지 마세요.
작성기(Composer) 상태만을 믿으세요.

AI 비디오 포스트의 경우, 다음 사항들이 확인되어야 합니다:

• 비디오 미리보기(Video preview)가 보이는 상태
• 업로드 진행률(Upload progress)이 완료된 상태
• 필요한 경우 플랫폼 공개 설정(Platform disclosure)이 선택된 상태
• 게시(Post) 버튼이 활성화된 상태
• 최종 게시된 포스트에 비디오가 표시되는 상태

브라우저 자동화(Browser automation)는 파일이 업로드되었다고 말하지만, 작성기(Composer)에 비디오가 나타나지 않는다면 워크플로우는 중단됩니다.

당연한 소리처럼 들리겠지만, 바로 이 지점에서 많은 자동화가 깨집니다.

대부분의 자동화는 실제 사용자에게 보이는 게시 상태가 아니라, API 호출이나 파일 입력(File input) 상태만을 확인하기 때문입니다.

기술(Skill)의 역할은 그 차이를 명확하게 유지하는 것입니다.

에이전트 친화적으로 만들기 (Making it agent-friendly)

다음 단계는 AI 에이전트(AI agent)가 사용하기 쉽게 워크플로우를 만드는 것입니다.

즉, 기술(Skill)에는 명확한 지침이 필요합니다:

## 에이전트 지침 (Agent Instructions)

1. `./make-x-safe.sh <video>`를 실행합니다.
...

무엇이 빠져 있는지 주목해 보세요:

모호한 "작동하게 만드세요(make it work)"

"준비되면 게시하세요(post when ready)"

40개의 예외 케이스(Edge cases)가 담긴 거대한 프롬프트(Prompt)

이 기술(Skill)은 에이전트에게 명확한 종료 조건(Stop condition)이 포함된 작은 운영 절차(Operating procedure)를 제공합니다.

이것이 훨씬 더 신뢰하기 쉽습니다.

무엇이 바뀌었나

기술(Skill) 적용 전:

비디오 생성.
업로드 시도.
실패하는 것을 지켜봄.
...

기술(Skill) 적용 후:

비디오 생성.
명령어 하나 실행.
출력 결과 확인.
...

워크플로우는 화려하지 않습니다.

화려한 것보다 더 나은 것, 즉 지루합니다.

그리고 프로덕션 미디어 준비(Production media prep)에서 제가 원하는 것은 바로 그 지루함입니다.

더 큰 교훈

이것이 제가 계속해서 터미널 기술(Terminal Skills)로 돌아오는 이유입니다.

유용한 AI 워크플로우는 대개 하나의 거대한 자율 에이전트(Autonomous agent)가 아닙니다.

그것은 문서화되고 재사용 가능한 작은 기능(Capabilities)들의 집합입니다:

• 업로드를 위한 비디오 준비
• 리포지토리(Repo) 검사
• 썸네일(Thumbnails) 생성
• 초안(Draft) 검증
• 이미지 크기 조정
• 링크 확인
• 승인 후에만 게시

각 기술(Skill)은 수동 기억(Manual memory)에 의존하는 취약한 조각 하나를 제거합니다.

각 기술(Skill)은 에이전트에게 더 좁은 범위의 업무를 부여합니다.

각 기술(Skill)은 더 깔끔한 완료 정의(Definition of done)를 만듭니다.

이것이 많은 AI 도구(AI tooling) 관련 대화에서 놓치고 있는 부분이라고 생각합니다.

미래는 단순히 "에이전트가 도구를 사용할 수 있다"는 것만이 아닙니다.

유용한 버전은 다음과 같습니다:

에이전트 (Agents)는 명확한 경계가 있는 잘 정의된 기술 (skills)을 사용할 수 있다.

그것이 바로 작업이 반복 가능해지는 방식입니다.

그리고 AI 비디오 업로드에 있어서는, 반복 가능함 (repeatable)이 영리함 (clever)을 언제나 압도합니다.

만약 당신이 AI 에이전트 (AI agents)로 무언가를 구축하고 있다면, 당신이 계속해서 수동으로 수정하고 있는 워크플로우 (workflow)는 무엇인가요?

그것이 아마도 당신의 다음 터미널 기술 (Terminal Skill)이 될 것입니다.

공지: 저는 이 글의 초안을 작성하고 편집하는 데 AI의 도움을 받았으며, 게시하기 전에 워크플로우 (workflow), 명령어 (commands), 그리고 주장 (claims)을 검토했습니다.