아카이브 / 개발
ai-shortform-studio — Codex 기반 숏폼 제작 도구
목차 — 프로젝트 요약 · 담당 범위 · 문제와 구현 접근 · 이 작업에서 한 일 · 결과물과 원문 · 구현 상세
프로젝트 요약
사람이 정한 편집 의도와 승인 기준 안에서 codex exec가 조사·기획·평가를 조율하고, Python CLI가 스키마 검사·렌더·감사·패키징을 재현 가능하게 수행하는 로컬 숏폼 제작 도구.
담당 범위
설계·구현을 맡은 개인 프로젝트다. 공개 저장소에 코드와 사용 방법을 남겼다.
문제와 구현 접근
제작을 plan → approve → produce → audit → evaluate → revise → package 단계로 나누고, 채널 명세·주제·주장·제작 계획·피드백·품질 보고를 JSON Schema로 검사한다. 에셋마다 출처·라이선스·생성 도구를 기록하고, AI로 생성했다는 사실을 숨기지 않고 공개 메타데이터로 결과물에 담는 것을 제작 원칙으로 두었다.
Python CLI는 FFmpeg 렌더(Pillow 자막 카드), 기술 감사, 파일별 SHA-256 manifest를 쓰는 ReleasePackage 패키징을 맡는다. 공급자를 교체 가능한 어댑터로 분리하는 원칙을 두고, 영상 생성은 Google Veo 어댑터로 구현했다. 이 어댑터는 기본적으로 비용 견적만 내는 dry-run으로 동작하고, 비용 상한·작업 저널·재호출 차단을 갖췄다.
첫 파일럿 채널 '배는 왜 거기로 갈까'의 첫 콘텐츠에는 공식 IMO·IHO 출처, 주장 원장, 권리 보고서와 AI 공개 문서를 함께 남겼고, v1 평가에서 나온 피드백을 v2에 반영했다. 2026년 7월 기준으로 음성과 믹스에 대한 사람의 청취 승인이 남아 있고, YouTube 업로드와 게시는 범위에 넣지 않았다.
이 작업에서 한 일
아이디어를 실제로 작동하는 코드로 만들고, 다른 사람이 설치하고 사용할 수 있도록 설명서를 함께 작성했다.
결과물과 원문
관련 등록공보·논문·저장소는 아래 링크에서 볼 수 있다.
구현 상세
README공개 저장소의 구조·기능·실행 문서
AI Shortform Studio
사람의 편집 의도를 보존하면서 codex exec로 AI 기반 숏폼 기획과 생성을 단계적으로 자동화하는 로컬 제작 도구입니다.
codex exec가 조사·기획·도구 선택·평가를 조율하고, 이 저장소의 Python CLI(shortform-studio)는 스키마 검사·음성 변환·렌더·감사·패키징을 재현 가능하게 수행합니다.
현재 단계
- 상태(2026-07-24 기준): 첫 파일럿 콘텐츠 v2의 제작·기술 감사·패키징까지 완료했고, 음성과 믹스에 대한 사람 청취 승인은 남아 있습니다.
- 첫 파일럿 채널:
배는 왜 거기로 갈까 - 범위: 주제 수집부터 배포 준비 영상 패키지 생성, 게시 후 성과 수동 반입까지
- 제외: YouTube 채널 생성, 업로드, 예약 게시, 댓글 운영, 수익 정산 자동화
제품 원칙
- 자동화보다 독창성과 수익화 적합성을 우선합니다.
- 사람은 채널의 관점과 승인 기준을 정하고,
codex exec는 기획·에셋 생성·검사 작업을 반복 실행합니다. - 에셋마다 출처, 라이선스, 생성 도구와 작업 ID를 기록합니다.
- AI 생성 사실을 숨기지 않으며 필요한 공개 메타데이터를 결과물에 포함합니다.
- 정책 적합성, 제작 안정성, 시청자 반응을 서로 다른 증거로 관리합니다.
- 자동 승인 범위는 실제 합격 데이터가 쌓인 뒤 위험도별로 확대합니다.
- Codex는 단일 제어면으로 사용하되 이미지·영상·음악 공급자는 교체 가능한 어댑터로 분리합니다.
저장소 구성
| 경로 | 내용 |
|---|---|
src/shortform_studio/ | shortform-studio CLI: 스키마 검사, macOS TTS 폴백, 사운드베드, FFmpeg 렌더(Pillow 자막 카드), 기술 감사, ReleasePackage 패키징(SHA-256 manifest) |
schemas/ | ChannelSpec, TopicBrief, Claims, ProductionPlan, Feedback, QualityReport JSON Schema(draft 2020-12) |
.agents/skills/produce-shortform/ | Codex 제작 스킬 $produce-shortform과 평가표 |
tools/ | Google Veo 단일 호출 어댑터(비용 상한·작업 저널·재호출 차단), Qwen3-TTS 로컬 음성 생성 스크립트 |
channels/, content/ | 파일럿 채널 명세와 첫 콘텐츠 why-ships-route-a01(출처, 주장 원장, 권리·AI 공개 문서, 피드백과 수정 이력, 장면 이미지, ReleasePackage 메타데이터) |
docs/ | 제품 요구사항, 실행 설계, 파일럿 계획, 정책·도구 조사, 작업 기록 |
문서
- 제품 요구사항 문서
- Codex exec 실행 설계
- 첫 파일럿 실행 계획
- 정책 및 도구 조사 기준
- 구현·실험 작업 기록
준비 사항
- macOS: 자막 카드와 설명 그래픽이 시스템 폰트
/System/Library/Fonts/AppleSDGothicNeo.ttc를 사용하고,tts-macos명령은 macOSsay를 호출합니다. - Python 3.9 이상과 uv
PATH에 있는 FFmpeg(ffmpeg,ffprobe): 렌더, 오디오 변환, 기술 감사에 사용합니다.- Codex CLI:
$produce-shortform스킬과codex exec단계 실행에 필요합니다. - 선택:
tools/qwen_tts_generate.py는torch,soundfile,qwen_tts가 필요하며pyproject.toml에 포함되지 않았으므로 별도 가상환경(예:.venv-qwen-tts/)에 설치합니다. - 선택:
tools/google_veo_generate.py는 환경 변수GEMINI_API_KEY를 읽습니다. 기본은 비용 견적만 출력하는 dry-run이며--execute를 줘야 과금 요청을 보냅니다.
로컬 실행
uv sync --extra dev
uv run pytest
uv run shortform-studio validate-tree첫 콘텐츠 제작은 프로젝트의 $produce-shortform 스킬과 다음 단계로 진행합니다.
plan -> approve -> produce -> audit -> evaluate -> revise -> package렌더와 패키지 명령:
uv run shortform-studio render --content-dir content/<content-id>
uv run shortform-studio audit --content-dir content/<content-id>
uv run shortform-studio package --content-dir content/<content-id>render는 승인된 production-plan.json을 읽어 work/final.mp4를 만들고, package는 이 영상과 메타데이터 문서를 release-package/로 복사한 뒤 파일별 SHA-256 manifest.json을 씁니다.
첫 파일럿 결과
content/why-ships-route-a01/에는 공식 IMO·IHO 출처, 주장 원장, 권리 보고서, AI 공개 문서, 사람 기여 기록, 장면 이미지와 썸네일, ReleasePackage 메타데이터가 들어 있습니다. v1 평가에서 나온 구독 CTA, 전문용어, 화면 반복성과 음성 압축 피드백을 v2에 반영했습니다.
제한 사항
- 영상·음성 바이너리는 커밋하지 않습니다. 최종 영상
release-package/final.mp4는package명령이 로컬에서 만드는 파일이며,manifest.json에는 그 크기와 해시만 기록되어 있습니다. - 파일럿의 나레이션과 사운드베드(
work/)도 커밋하지 않았으므로, 파일럿을 다시 렌더하려면 이 파일들을 먼저 로컬에서 생성해야 합니다. - 폰트 경로가 macOS 기준으로 고정되어 있어 다른 OS에서는 렌더와 그래픽 생성 코드를 수정해야 합니다.
- YouTube 업로드와 게시는 이 저장소의 범위가 아닙니다.