한 줄 요약: browser-use/video-use는 영상 편집 프로그램이 아닙니다. Claude Code나 Codex 같은 코딩 에이전트에 끼워 넣는 “스킬 + 파이썬 헬퍼 6개” 묶음입니다. 에이전트가 영상을 프레임 단위로 들여다보는 대신, 단어 단위 타임스탬프가 붙은 전사 텍스트(약 12KB)를 읽고 컷을 고릅니다. 그 결정을 EDL(JSON)로 적으면 ffmpeg 파이프라인이 정해진 순서대로 렌더링합니다. 라이선스는 MIT입니다. 아래에서는 저장소 구조, 전사부터 렌더까지의 흐름, SKILL.md의 ‘하드 룰 12개’, 비슷한 도구와의 비교를 다룹니다. 문서와 코드가 어긋나는 곳과 운영할 때의 주의점도 짚었습니다. 마지막으로 박스에서 유료 API 키 없이 돌릴 수 있는 범위만 실제로 돌린 결과를 정리했습니다.
1. 지금 트렌딩에 있는 이유와 기본 정보
2026-10-26(월) 오후 GitHub Trending 데일리 Python 5위(오늘 +97)에 올라 있습니다. 전체 랭킹 상위권에는 들지 못했습니다. 다만 4월에 만들어진 저장소가 반년 만에 별 3만 개 가까이 모았고, 지금도 매일 꾸준히 별이 붙고 있습니다. 만든 곳은 웹 에이전트 라이브러리 browser-use(별 약 11.9만 개)를 운영하는 Browser Use 팀입니다. 10월 8일 커밋에서 README에 호스팅형 video-use 대기자 명단 링크가 붙었습니다. “코딩 에이전트가 이제 영상도 편집한다”는 이야기가 퍼지면서 관심이 이어지는 것으로 보입니다. 이 글은 저장소 최신 커밋 43cfc56(2026-10-09 07:16 KST) 기준입니다.
| 항목 | 값 (2026-10-26 KST 확인) | 메모 |
|---|---|---|
| 저장소 | browser-use/video-use |
설명: “Edit videos with coding agents” |
| 라이선스 | MIT | Copyright (c) 2026 Browser Use. 라이선스 파일은 5월 PR #32로 추가 |
| 스타 / 포크 | 29,856 / 3,463 | GitHub API, 오후 5시 전후 |
| 트렌딩 | 데일리 Python 5위 (+97) | 전체 데일리 상위 11위 안에는 없음 |
| 생성일 | 2026-04-12 10:34 KST | 약 6개월 차 |
| 릴리스 / 태그 | 없음 | pyproject.toml 버전은 0.1.0 그대로. 사실상 main 브랜치를 따라가는 롤링 방식 |
| 커밋 수 | 23개 | 코드량이 작고, 기능 확장은 대부분 열린 PR에 몰려 있음 |
| 열린 이슈+PR | 159개 | EDL v2, 로컬 Whisper 전사, 오디오 트랙 믹싱 같은 큰 PR이 대기 중 |
| 요구 사항 | Python 3.10 이상, ffmpeg/ffprobe, ElevenLabs API 키 | 애니메이션을 쓸 때만 Node.js(HyperFrames는 22 이상)나 Manim 필요 |
| 파이썬 의존성 | requests, librosa, matplotlib, pillow, numpy | 선택 항목 animations = ["manim"] |
2. 문제 정의: 왜 영상을 ‘보지’ 않고 ‘읽게’ 하나
README의 계산은 이렇습니다. 30,000프레임짜리 영상을 프레임마다 약 1,500토큰짜리 이미지로 넣으면 4,500만 토큰이 됩니다. 대부분은 편집 판단에 쓸모없는 잡음입니다. 그래서 video-use는 Browser Use가 웹 에이전트에서 써 온 방식을 영상에 그대로 가져옵니다. 웹에서 스크린샷 대신 구조화된 DOM을 주듯이, 영상에서는 프레임 대신 구조화된 전사를 줍니다.
이 선택에는 분명한 전제가 깔려 있습니다. 말하는 사람이 나오는 영상(토킹헤드, 튜토리얼, 인터뷰, 런칭 영상)에서는 컷 위치를 소리가 정한다는 것입니다. SKILL.md의 두 번째 원칙인 “Audio is primary, visuals follow”가 바로 이 내용입니다. 컷 후보는 단어 경계와 침묵 구간에서 나오고, 화면은 애매한 지점에서만 확인합니다. 반대로 말소리가 거의 없는 몽타주나 B롤 위주 영상에서는 이 전제가 약해집니다. README는 이런 영상도 다룬다고 하지만, 판단 근거가 줄어든다는 점은 감안해야 합니다(9장).
3. 저장소 구조: 코드는 작고, 규칙 문서가 크다
저장소를 열어 보면 생각보다 작습니다. 파이썬 헬퍼 6개를 합쳐도 2,100줄 남짓입니다. 오히려 에이전트가 읽는 SKILL.md(26KB, 342줄)와 install.md가 제품의 핵심입니다. 코드는 “틀리면 조용히 망가지는 일”을 대신 처리하고, 편집 판단은 문서를 읽은 LLM이 맡습니다.
| 경로 | 줄 수 | 역할 |
|---|---|---|
SKILL.md |
342 | 에이전트용 운영 매뉴얼. 원칙 7개, 하드 룰 12개, 편집 절차 8단계, 컷·색보정·자막·애니메이션·사운드 작업 요령, EDL 형식, 안티패턴 |
install.md |
— | 에이전트가 스스로 설치할 때 따르는 절차. 클론, 의존성 설치, ffmpeg, 스킬 등록(심볼릭 링크), API 키 입력과 확인 |
helpers/transcribe.py |
241 | ffmpeg로 16kHz 모노 WAV를 뽑아 ElevenLabs Scribe에 업로드하고, 응답 JSON을 캐시 |
helpers/transcribe_batch.py |
126 | 폴더 단위 병렬 전사(기본 워커 4개). 이미 전사한 파일은 건너뜀 |
helpers/pack_transcripts.py |
206 | 단어 단위 JSON을 구절 단위 마크다운 takes_packed.md로 압축 |
helpers/timeline_view.py |
392 | 지정한 구간의 필름스트립, 파형, 단어 라벨, 침묵 구간 음영을 PNG 한 장으로 출력 |
helpers/render.py |
801 | EDL을 받아 구간 추출 → 무손실 이어붙이기 → 오버레이 → 자막 → 라우드니스 정규화 순서로 렌더 |
helpers/grade.py |
375 | 색보정 프리셋(subtle, neutral_punch, warm_cinematic, none), 원본 ffmpeg 필터, 구간별 자동 보정(auto) |
skills/manim-video/ |
문서 14개 + 스크립트 | 수식·다이어그램 애니메이션용 Manim 하위 스킬을 저장소에 포함 |
tests/ |
3개 파일 | 자막 청킹, fps 보존, 세로 영상·회전 판정 회귀 테스트 |
콘솔 스크립트(CLI 진입점)는 없습니다. 헬퍼는 python helpers/<name>.py처럼 직접 실행합니다. 스킬로 등록할 때는 저장소 디렉터리 전체를 심볼릭 링크로 연결해야 합니다. SKILL.md가 헬퍼를 상대 경로로 부르기 때문에, SKILL.md만 복사하면 헬퍼를 찾지 못합니다.
4. 동작 원리 ① 전사와 압축: Layer 1
transcribe.py가 Scribe에 보내는 요청은 코드에 고정돼 있습니다. model_id=scribe_v1, diarize=true(화자 분리), tag_audio_events=true(웃음·박수 같은 소리 표시), timestamps_granularity=word(단어 단위 시간)입니다. 언어는 따로 지정하지 않으면 자동 감지하고, --language로 지정할 수 있습니다. 화자 수를 알면 --num-speakers로 넘겨 화자 분리 정확도를 높일 수 있습니다.
세부 구현에서 실무에 도움이 되는 부분이 몇 가지 있습니다.
- 오디오 트랙 선택(8월 PR #134): ffmpeg는 기본적으로 채널이 가장 많은 오디오 트랙을 고릅니다. OBS처럼 0번 트랙에 게임 소리, 1번 트랙에 마이크를 녹음하는 경우에는 엉뚱한 트랙이 전사됩니다.
--audio-track N으로 트랙을 고를 수 있고, 캐시 파일명에도.trackN이 붙습니다. - 무음 업로드 차단: 추출한 WAV의 피크가 -60 dBFS보다 낮으면 업로드하지 않고 바로 예외를 냅니다. 무음도 업로드하면 똑같이 비용이 나가기 때문입니다.
- 캐시는 불변으로 취급: 결과 JSON이 이미 있으면 업로드하지 않습니다. 하드 룰 9번도 “원본 파일이 바뀌지 않았으면 다시 전사하지 말라”입니다. 다만 코드는 파일 이름으로만 캐시 적중을 판단합니다. 같은 이름으로 원본을 교체했다면 캐시 JSON을 직접 지워야 합니다.
pack_transcripts.py는 단어 목록을 순서대로 훑습니다. 0.5초 이상 침묵이 있거나 화자가 바뀌면 구절을 끊고, 각 구절 앞에 [시작-끝] 시간을 붙여 마크다운 한 파일로 모읍니다. 여기서 핵심 설계는 필러를 지우지 않는다는 점입니다. SKILL.md는 Whisper의 SRT나 구절 단위 출력, 필러를 정리해 주는 정규화 모드를 안티패턴으로 꼽습니다. 1초 미만의 간격 정보와 “umm, uh” 같은 편집 신호가 사라지기 때문입니다. 로컬 CPU로 Whisper를 돌리는 것도 “느리고 필러를 정규화한다”는 이유로 권하지 않습니다. 이 결정이 곧 외부 유료 API에 대한 의존으로 이어지고, 그래서 로컬 Whisper 전사 PR(#151)이 아직 열려 있는 상태입니다.
5. 동작 원리 ② 시각 확인과 EDL: Layer 2
timeline_view.py <video> <start> <end>는 지정한 구간에서 프레임 N장(기본 10장)을 뽑아 필름스트립을 만들고, 그 아래에 파형, 단어 라벨, 0.4초 이상 침묵 구간 음영을 그립니다. 전사 파일은 <영상 폴더>/edit/transcripts/<파일명>.json에서 자동으로 찾습니다. SKILL.md는 이 도구를 “스캔용이 아니다”라고 분명히 적습니다. 애매한 침묵, 테이크 비교, 컷 지점 확인처럼 판단이 필요한 순간에만 부르라는 뜻입니다. 이미지는 토큰을 많이 쓰기 때문에 이 규칙이 비용 관리 수단이 됩니다. --edl 옵션은 도움말에 “Not yet implemented”라고 나와 있습니다.
LLM이 편집을 결정하면 결과는 EDL 한 파일에 담깁니다. 원본 경로(sources), 구간 목록(ranges: source, start, end, beat, quote, reason), 색보정(grade), 오버레이, 자막, 예상 길이가 들어갑니다. 구간마다 reason을 적게 한 덕분에, 사람이 나중에 “왜 이 테이크를 골랐는지” 검토할 수 있습니다. 테이크가 여러 개일 때는 편집 전담 서브에이전트에게 정해진 형식의 브리프를 주고, JSON 배열만 돌려받습니다. 브리프에는 런칭, 튜토리얼, 인터뷰 같은 구성 유형 예시와 규칙이 들어갑니다. 규칙은 단어 경계에서만 자르기, 30~200ms 여유 두기, 400ms 이상 침묵을 우선 컷 지점으로 쓰기 등입니다.
6. 동작 원리 ③ 렌더 파이프라인과 ‘하드 룰’
SKILL.md는 스스로를 “규칙 12개만 지키면 나머지는 자유”라고 설명합니다. 이 12개 중 상당수는 render.py에 코드로 구현돼 있습니다. 어떤 규칙이 코드로 보장되고 어떤 규칙이 에이전트의 성실함에 달려 있는지 구분해 두면 운영할 때 도움이 됩니다.
| # | 하드 룰 | 지키지 않으면 | 강제 주체 |
|---|---|---|---|
| 1 | 자막은 필터 체인의 맨 마지막 | 오버레이에 자막이 가려짐 | 코드: build_final_composite가 마지막에 subtitles 필터 적용 |
| 2 | 구간별로 추출한 뒤 -c copy로 이어붙이기 |
오버레이를 넣을 때 이중 인코딩 | 코드: concat demuxer 사용, fps를 하나로 통일 |
| 3 | 모든 경계에 30ms 오디오 페이드 | 컷마다 ‘틱’ 소리 | 코드: afade in/out 0.03초 |
| 4 | 오버레이에 setpts=PTS-STARTPTS+T/TB |
애니메이션 중간부터 보임 | 코드 |
| 5 | 자막 시간을 출력 타임라인 기준으로 계산 | 이어붙인 뒤 자막 어긋남 | 코드: --build-subtitles 사용 시 |
| 6 | 단어 중간에서 자르지 않기 | 말이 잘림 | 에이전트(EDL 작성 시) |
| 7 | 컷 경계에 30~200ms 여유 | Scribe 타임스탬프 오차 50~100ms에 걸림 | 에이전트 |
| 8 | 단어 단위 원문 그대로의 ASR만 사용 | 침묵·필러 신호 손실 | 코드(전사 파라미터 고정) + 에이전트 |
| 9 | 전사 캐시, 재전사 금지 | 비용 중복 | 코드(파일 이름 기준) |
| 10 | 애니메이션 여러 개는 병렬 서브에이전트로 | 전체 작업 시간 증가 | 에이전트(Agent 도구가 있는 하네스 전제) |
| 11 | 전략을 승인받기 전에는 컷 금지 | 사용자 의도와 다른 편집 | 에이전트 |
| 12 | 모든 산출물은 <영상 폴더>/edit/에 |
스킬 디렉터리 오염 | 에이전트(렌더 결과는 EDL 위치 기준으로 저장) |
여기에 코드가 알아서 처리하는 품질 장치도 있습니다. HLG/PQ 같은 HDR 원본은 Rec.709 SDR로 톤 매핑합니다. 회전 메타데이터를 반영해 세로 영상을 판정합니다(PR #137). 원본 fps를 유지하고 필요하면 --fps로 바꿀 수 있습니다(PR #55). 마지막에는 2패스 loudnorm으로 -14 LUFS, 트루 피크 -1 dBTP, LRA 11에 맞춥니다. 끄려면 --no-loudnorm을 씁니다. 품질 단계는 세 가지입니다.
| 모드 | 해상도 | x264 프리셋 / CRF | 용도 |
|---|---|---|---|
| 기본(final) | 1080p(긴 변 1920) | fast / 20, 최종 합성은 CRF 18 | 최종 출력 |
--preview |
1080p | medium / 22 | 품질 점검용 미리보기 |
--draft |
720p | ultrafast / 28, loudnorm은 1패스 | 컷 위치만 빠르게 확인 |
README의 “렌더 결과를 스스로 평가한다(Self-Eval)”는 코드 기능이 아닙니다. SKILL.md 7단계에 적힌 절차입니다. 렌더 결과의 모든 컷 경계 ±1.5초 구간에 timeline_view를 돌리고, ffprobe로 길이를 확인하고, ebur128로 음량을 측정하라는 지시입니다. 공개용 영상이라면 칭찬 대신 비판만 하는 비평 서브에이전트를 하나 더 띄우라고도 적혀 있습니다. 재시도는 3회까지입니다. 에이전트가 이 절차를 건너뛰어도 막는 장치는 없습니다. 품질은 하네스와 모델이 지시를 얼마나 잘 따르는지에 달려 있습니다. 문서에 “당신은 들을 수 없다. 그렇다고 말하고 수치를 보고하라”라는 문장이 있는 것도 같은 이유입니다.
7. 설치와 실행
공식적으로 권하는 방법은 README의 “설치 프롬프트”를 에이전트에 붙여 넣는 것입니다. 에이전트가 install.md를 읽고 클론, 의존성 설치, 스킬 등록을 한 뒤, API 키가 필요할 때 한 번만 묻습니다. 사람이 직접 설치한다면 다음과 같습니다.
# 1) 안정적인 경로에 클론하고, 저장소 전체를 스킬 디렉터리에 링크
git clone https://github.com/browser-use/video-use ~/Developer/video-use
ln -sfn ~/Developer/video-use ~/.claude/skills/video-use # Claude Code
# ln -sfn ~/Developer/video-use "${CODEX_HOME:-$HOME/.codex}/skills/video-use" # Codex
# 2) 의존성 설치
cd ~/Developer/video-use
uv sync # 또는 pip install -e .
sudo apt-get install -y ffmpeg # macOS는 brew install ffmpeg
# 3) ElevenLabs 키 (파일 권한 600 권장, 커밋 금지)
cp .env.example .env && chmod 600 .env && $EDITOR .env # ELEVENLABS_API_KEY=...
# 4) 비용이 들지 않는 확인
python helpers/timeline_view.py --help >/dev/null && echo "helpers OK"
ffprobe -version | head -1실제 편집은 영상이 있는 폴더에서 에이전트를 실행하고 말로 지시합니다. 예를 들면 “edit these into a launch video”입니다. 헬퍼를 사람이 직접 호출할 수도 있습니다. 파이프라인을 CI에 넣거나 디버깅할 때 유용합니다.
cd /path/to/videos
python ~/Developer/video-use/helpers/transcribe_batch.py . # 유료: Scribe 호출
python ~/Developer/video-use/helpers/pack_transcripts.py --edit-dir edit
python ~/Developer/video-use/helpers/timeline_view.py C0101.mp4 3.0 7.5 -o edit/verify/c0101.png
python ~/Developer/video-use/helpers/grade.py --list-presets
python ~/Developer/video-use/helpers/render.py edit/edl.json -o edit/preview.mp4 --preview --build-subtitles
ffmpeg -i edit/preview.mp4 -af ebur128=peak=true -f null - # 음량 확인8. 박스 스모크 테스트: 유료 API 없이 확인한 것과 못 한 것
ElevenLabs 키 없이 할 수 있는 범위만 실제로 돌렸습니다. 환경은 Debian 계열 박스, Python 3.13.5, ffmpeg 7.1.5(libass·loudnorm·ebur128 포함), uv sync(약 2초)입니다. 원본 영상은 testsrc2로 만든 1920×1080 30fps 합성 영상 두 개(12초, 10초)입니다. 오디오는 “단어” 구간에만 220Hz 톤이 나오고 웃음 구간에는 잡음을 넣었습니다. 전사 JSON은 Scribe 응답 형식(word, spacing, audio_event 타입과 speaker_id)을 그대로 따라 손으로 만들었습니다. 즉 실제 음성 인식은 검증 범위 밖이고, 전사 결과를 받은 뒤의 파이프라인만 확인했습니다.
| 시험 | 명령 | 결과 |
|---|---|---|
| 단위 테스트 | uv run pytest -q tests |
26 passed, 15 subtests passed (0.06초) |
| 전사 압축 | pack_transcripts.py --edit-dir footage/edit |
2개 전사 → 9구절, 536바이트. umm/uh가 별도 구절로 남고 (laughter)도 표시됨 |
| 키 없을 때 | transcribe.py (키 없음) |
ELEVENLABS_API_KEY not found ..., 종료 코드 1 |
| 캐시 적중 | transcribe.py (임의 키, JSON 존재) |
cached: C0101.json, 네트워크 호출 없음 |
| 무음 차단 | 무음 트랙 영상에 transcribe.py |
track 1 of S1.mp4 is silent (peak -inf dBFS) - not uploading, 업로드 전에 중단 |
| 시각 확인 | timeline_view.py C0101.mp4 3.0 7.5 |
2.6초, 270KB PNG. 필러 구간과 침묵 음영이 정상 표시(본문 이미지) |
| 렌더 | render.py edl.json -o preview.mp4 --preview --build-subtitles |
구간 4개(필러 제거, 웃음 비트 유지), 오버레이 1개, 자막 8큐. 실행 7.7초, 7.9MB, h264 1920×1080 30fps |
| 길이 검증 | ffprobe |
7.80초 (EDL 합계 7.74초, AAC 프레임 단위 차이 약 0.06초) |
| 음량 | ebur128=peak=true |
통합 -13.8 LUFS(목표 -14), LRA 2.9 LU, 트루 피크 -8.5 dBFS |
| 자막 순서 | 2.0초 지점 프레임 추출 | 오버레이 위에 자막(“WASTE TOKENS.”)이 그려짐. 하드 룰 1 확인 |
이 과정에서 문서만 봐서는 알기 어려운 점이 몇 가지 드러났습니다.
- 오버레이 위치를 지정할 방법이 없습니다. 코드는
overlay필터에 x/y 값 없이 시간 조건(enable)만 넘깁니다. 그래서 600×200 테스트 클립이 화면 왼쪽 위(0,0)에 붙었습니다. 특정 위치에 띄우려면 애니메이션을 전체 해상도로 렌더링하고 배경을 투명하게 만들거나, EDL v2 PR(#147, overlay layouts)이 합쳐지기를 기다려야 합니다. - 자막 위치가 문서와 코드에서 다릅니다. SKILL.md의
bold-overlay예시는MarginV=35입니다. 하지만render.py의SUB_FORCE_STYLE은 세로 영상 플랫폼의 UI 영역을 피하려고MarginV=90을 씁니다(4월 PR #5). 실제로 자막이 화면 하단에서 약 30% 위에 표시됐습니다. 가로 16:9 영상만 만든다면 너무 높아 보일 수 있습니다. - Helvetica 대체 글꼴. 리눅스에는 Helvetica가 없어서 박스에서는 fontconfig가 Nimbus Sans로 대체했습니다. 오류는 나지 않습니다. 한글 자막이라면
FontName을 한글 글꼴로 바꿔야 합니다. - 자막은 영문 대문자 기준으로 설계돼 있습니다. 2단어 묶음,
.upper(), 구두점 기준 분리는 영어에 맞춘 것입니다. 한국어에서는 대문자 변환이 의미가 없고, 2어절 단위가 너무 짧게 느껴질 수 있습니다. SKILL.md도 문장형 자막(natural-sentence)은 “필요하면 직접 설계하라”고만 적고 있습니다. - 자막 생성이 EDL의 source 키로 전사를 찾습니다.
build_master_srt는transcripts/<source 키>.json을 엽니다. EDL의 source 키를 파일 이름(stem)과 다르게 지었거나--audio-track으로.trackN.json을 만들었다면, 해당 구간 자막이 경고 한 줄만 남기고 빠집니다.
확인하지 못한 것도 분명히 적어 둡니다. 실제 Scribe 전사(유료), Claude Code나 Codex 안에서의 대화형 편집 전체 흐름, HyperFrames·Remotion·Manim 애니메이션 슬롯, 4K/HDR 원본은 돌리지 않았습니다.
9. 비슷한 도구와 비교
| 도구 | 방식 | 라이선스 / 규모 | 강점 | video-use 대비 약점 |
|---|---|---|---|---|
| browser-use/video-use | 코딩 에이전트 스킬. LLM이 전사를 읽고 EDL 작성 → ffmpeg | MIT / 약 2.99만★ | 내용을 이해한 컷 선택(테이크 비교, 비트 구성), 대화로 수정, 자막·색보정·애니메이션까지 | — |
| auto-editor | 음량·모션 임계값으로 무음 구간 자동 삭제(CLI) | Unlicense / 약 5,600★ | 오프라인, 빠름, 비용 없음, 결과 예측 가능 | 내용을 이해하지 못함. 말실수나 더 나은 테이크를 고르지 못함 |
| LosslessCut | 사람이 직접 하는 무손실 컷 GUI | GPL-2.0 / 약 4.5만★ | 재인코딩 없이 빠른 자르기 | 자동화·전사 기반 편집 없음 |
| Remotion / HyperFrames | React 또는 HTML로 영상을 ‘생성’ | Remotion은 자체 라이선스(회사 규모에 따라 유료) / HyperFrames Apache-2.0 | 모션 그래픽, 데이터 기반 영상 | 촬영 원본 편집 도구가 아님. video-use는 이 둘을 오버레이 엔진으로 가져다 씀 |
| Whisper(whisperX) + 직접 만든 스크립트 | 로컬 ASR → 직접 컷 로직 작성 | whisperX BSD-2 / 약 2.5만★ | 로컬 처리로 데이터가 외부에 나가지 않음, 비용 없음 | 필러 정규화, 렌더 순서, 페이드 같은 함정을 직접 처리해야 함 |
| Descript 같은 상용 텍스트 기반 편집기 | 전사 텍스트를 지우면 영상도 잘림(GUI) | 상용 SaaS | 사람이 다루기 쉬운 UI, 협업 | 에이전트 자동화나 코드 수준의 제어가 제한적 |
정리하면 video-use는 “규칙 기반 자동 컷”(auto-editor)과 “사람용 텍스트 편집기”(Descript류) 사이에 있습니다. 판단은 LLM에, 정확성은 코드에 나눠 맡긴 구조입니다. 비교 대상 중 이 경계를 문서(하드 룰과 원칙)로 명시한 도구는 드뭅니다.
10. 트레이드오프, 비용, 보안
| 쟁점 | 내용 | 실무 대응 |
|---|---|---|
| 데이터 외부 전송 | 모든 원본의 오디오가 16kHz WAV로 ElevenLabs에 업로드됩니다. 회의 녹화나 고객 인터뷰처럼 민감한 음성이 외부로 나갑니다 | 사내 정책과 ElevenLabs 데이터 처리 조건 확인. 민감한 영상은 로컬 Whisper PR(#151)이 합쳐질 때까지 사용 보류 |
| 비용 | Scribe 전사 비용과, 판단을 맡는 LLM 토큰 비용이 따로 듭니다. timeline_view PNG를 자주 부르면 이미지 토큰도 늘어납니다 | 캐시 유지(재전사 금지), --draft로 컷 먼저 확인, 시각 확인은 판단 지점에서만 |
| 에이전트 권한 | 설치 프롬프트가 에이전트에게 clone, 패키지 설치, 스킬 디렉터리 쓰기를 맡깁니다. install.md는 sudo가 필요하면 사용자에게 묻도록 하고 있습니다 | 설치는 사람이 직접 하거나 승인 모드로 진행. 셸 권한이 넓은 에이전트는 샌드박스에서 실행 |
| API 키 관리 | 키는 저장소 루트 .env 또는 환경 변수에서 읽습니다. 현재 작업 폴더의 .env도 탐색합니다 |
chmod 600, 저장소 .gitignore 확인. 영상 폴더에 다른 .env가 있으면 그 키가 쓰일 수 있음을 기억 |
| 임의 경로 접근 | EDL의 sources와 오버레이 file은 임의의 경로를 받습니다. subprocess는 리스트 인자를 써서 셸 인젝션 위험은 낮지만, ffmpeg가 그 파일을 읽습니다 |
외부에서 받은 EDL을 그대로 렌더하지 말 것. 경로 허용 목록 적용 |
| 버전 고정 불가 | 릴리스와 태그가 없고 버전이 0.1.0으로 고정돼 있습니다. 설치 문서도 git pull --ff-only를 권합니다 |
운영 환경에서는 커밋 해시로 고정. 큰 PR(EDL v2 등)이 합쳐지면 EDL 호환성 다시 확인 |
| 품질이 모델에 좌우됨 | 자기 평가, 전략 승인, 병렬 서브에이전트는 모두 지시문입니다. Agent 도구가 없는 하네스에서는 병렬 처리 규칙을 지킬 수 없습니다 | 렌더 뒤 ffprobe/ebur128 점검을 CI 스크립트로 별도 실행 |
| 잘 맞는 영상 | 말 중심(토킹헤드, 튜토리얼, 인터뷰, 런칭 영상)에서 강합니다. 말이 적은 몽타주는 판단 근거가 얇아집니다 | 몽타주는 timeline_view 비중을 늘리거나 사람이 EDL을 직접 손보기 |
11. 누구에게 쓸 만한가
이미 Claude Code나 Codex를 매일 쓰고, 말 중심 영상을 자주 만드는 개발자나 데브렐 팀이라면 바로 써 볼 만합니다. 제품 데모, 기술 튜토리얼, 사내 발표 녹화가 여기에 해당합니다. 필러 제거, 테이크 선택, 음량 맞추기, 자막 같은 반복 작업을 대화 몇 번으로 줄일 수 있습니다. 렌더 단계는 결정적인 ffmpeg 파이프라인이라 결과를 재현하기도 쉽습니다. 직접 해 보면 이 저장소의 진짜 가치는 코드 2천 줄보다 SKILL.md에 정리된 편집 노하우와 함정 목록에 있다는 것을 알 수 있습니다. 단어 경계 여유, 30ms 페이드, 자막을 맨 마지막에 넣는 순서, -14 LUFS 같은 내용입니다. 반대로 데이터를 외부로 보낼 수 없는 조직, 한글 자막 품질이 중요한 채널, 버전을 고정해야 하는 운영 환경이라면 한 템포 쉬는 편이 낫습니다. 로컬 전사, EDL v2, 오버레이 배치 PR이 정리된 뒤에 다시 검토하기를 권합니다.