이 레포가 무엇을 하는 물건인가.
웹 기반 영상 도구의 통상 구조(업로드→서버 처리→다운로드)를 버리고, 처리 엔진 자체를 사용자 브라우저로 가져왔습니다. 결과: 100MB 영상도 업로드 대기 0초, 회사 기밀 영상도 외부 유출 걱정 0, 그리고 비행기 안에서도 동작.
기능은 데스크탑 편집기 부럽지 않습니다 — 2-pass 팔레트 GIF 제작, CRF 슬라이더 압축(실시간 용량 추정), 트림(모든 작업에 중첩 적용), 속도 변경(atempo 체인으로 음정 보존), 페이드·밝기/대비/채도·자막 임베드·영상 이어붙이기·PiP·오디오 믹싱까지. 그리고 UI에 없는 건 raw ffmpeg 명령 입력으로 — 이름이 "webCLI"인 이유입니다.
트렌딩 이유 · 경쟁 대비 장점.
온라인 영상 변환 사이트는 수십 개지만 거의 전부 업로드 방식 — 느리고, 용량 제한 있고, 내 영상이 남의 서버를 거칩니다. ffmpeg-webCLI는 "로컬 처리 + 오프라인 PWA + 광고/수집 없음"이라는 3무(無)로 차별화했고, 13개 파일짜리 미니멀 구현이라 "나도 읽고 베낄 수 있다"는 점이 개발자 트렌딩의 동력이 됐습니다.
| 비교 항목 | 업로드형 변환 사이트 | ffmpeg webCLI |
|---|---|---|
| 데이터 이동 | 내 영상이 서버로 | 기기 밖으로 1바이트도 안 나감 |
| 속도 병목 | 업/다운로드 대역폭 | 내 CPU (Wasm 멀티스레드) |
| 오프라인 | 불가 | PWA — 첫 방문 후 완전 오프라인 |
| 유연성 | 제공 메뉴만 | 32+ 작업 + raw ffmpeg 명령 탈출구 |
ffmpeg-core의 pthreads는 SharedArrayBuffer를 요구하는데, Spectre 보안 이슈 이후 브라우저는 COOP/COEP 헤더(교차 출처 격리)가 설정된 페이지에서만 이를 허용합니다. GitHub Pages 같은 정적 호스팅에선 헤더를 못 박죠.
서비스워커가 응답을 가로채 COOP/COEP 헤더를 끼워 넣는 우회(coi-serviceworker.js)로 정적 호스팅에서도 멀티스레드를 살렸고, 자체 서버(server.js)로 띄울 땐 진짜 헤더를 설정합니다 — 같은 문제의 두 해법을 한 레포에서 비교할 수 있습니다.
프레임워크 없는 바닐라 웹 스택.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 처리 엔진 | ffmpeg.wasm (ffmpeg-core-mt) | ffmpeg 전체를 Wasm으로 — 멀티스레드(pthreads) 버전. |
| 백그라운드 실행 | Web Worker (docs/worker.js) | 인코딩 중에도 UI가 멈추지 않게 분리. |
| 격리 헤더 | coi-serviceworker.js / server.js | SharedArrayBuffer 활성화의 두 경로 (정적 호스팅용 / 자체 서버용). |
| 오프라인 | PWA (service-worker.js + manifest.json) | 에셋·Wasm 캐싱 — 설치형 앱처럼 동작. |
| UX 디테일 | Screen Wake Lock API | 긴 인코딩 중 화면 꺼짐 방지. |
| 자동 자막(STT) | Transformers.js + Whisper (docs/transcriber.js) | 브라우저 내 온디바이스 STT — 서버 없이 자막 자동 생성. |
| 배치 처리 | Batch + Stack mode (docs/index.html) | 여러 파일에 작업 체인을 한 번에 적용 — 25개 작업 지원. |
| 프론트엔드 | 바닐라 HTML/JS (docs/index.html) | 프레임워크 0 — 전체가 한 줌의 파일. |
영상 파일 하나가 GIF가 되어 나오기까지 — 전부 브라우저 안.
구조의 묘미는 "UI는 명령 조립기일 뿐"이라는 점입니다. GIF 메뉴도, 압축 슬라이더도 결국 ffmpeg 명령 문자열을 만들어 워커에 넘깁니다 — 그래서 raw CLI 모드가 자연스럽게 존재하고, ffmpeg을 아는 사람에겐 학습 비용이 0입니다. 속도 변경 기능이 0.5~2.0 범위 제한이 있는 atempo 필터를 자동으로 체인(예: 4× = atempo=2.0,atempo=2.0)하는 디테일에서, "ffmpeg 사용법의 모범 답안 모음"이라는 부가 가치도 생깁니다.
세탁소에 옷을 맡기는 대신(업로드형), 전문가용 세탁기를 우리 집에 들여놓은 격입니다(Wasm). 버튼식 코스(UI 메뉴)도 있고, 다이얼을 직접 돌리는 수동 모드(raw 명령)도 있는 — 옷은 집 밖으로 안 나갑니다.
13개 파일 전부가 한눈에.
| 위치 | 주목할 점 |
|---|---|
docs/index.html | 30+ 작업의 ffmpeg 명령 레시피가 모두 여기 — ffmpeg 치트시트로도 가치. |
server.js | 주석이 친절한 60줄급 정적 서버 — "왜 이 헤더가 필요한가"가 코드에 설명됨. |
coi-serviceworker.js | 정적 호스팅에서 교차 출처 격리를 얻는 커뮤니티 표준 패턴. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
멀티스레드 Wasm의 전제조건(SharedArrayBuffer→COOP/COEP), 정적 호스팅의 한계와 서비스워커 우회, 워커 분리 — "브라우저에서 ffmpeg급 도구 돌리기"의 모든 관문이 최소 코드로 시연됩니다.
2-pass 팔레트 GIF, CRF/preset 트레이드오프, atempo 체인, reverse+areverse, eq 필터 — index.html의 명령 조립부는 ffmpeg 학습 자료로 그대로 씁니다.
manifest + 서비스워커 캐싱 + Wake Lock — 설치형 웹 앱의 뼈대를 군더더기 없이 보여줍니다.
서버 없이 Whisper 모델을 브라우저에서 직접 돌려 자동 자막을 생성합니다 — docs/transcriber.js가 전담 워커. Wasm 처리 엔진(ffmpeg)과 AI 추론(Transformers.js) 두 무거운 작업이 모두 로컬에서 돌아가는 구조를 비교해볼 수 있습니다.
25개 작업을 여러 파일에 일괄 적용하는 배치 처리와, 작업들을 순서대로 묶어 한 번에 실행하는 Stack 모드를 제공합니다 — "UI가 ffmpeg 명령 조립기"라는 설계가 배치·체이닝으로 자연스럽게 확장되는 과정을 읽을 수 있습니다.
같은 기능이라도 데이터가 어디서 처리되는가로 신뢰·속도·오프라인이 갈립니다 — 프라이버시를 아키텍처로 보장하는 작은 본보기.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 사용자 | 모던 브라우저면 끝 — 라이브 앱 접속 또는 PWA 설치. |
| 메모리 | 처리할 영상이 브라우저 메모리에 올라감 — 수 GB급 대형 파일은 한계. |
| 자체 호스팅 | node server.js 한 줄 (기본 포트 5500, COOP/COEP 포함) 또는 node server.js 8080으로 포트 지정. 아무 정적 호스팅도 가능(coi-serviceworker가 커버). |
| 성능 | 인코딩 속도 = 내 CPU. 네이티브 ffmpeg보다는 느리지만 업로드 시간이 없어 체감은 종종 더 빠름. |
난이도별로 손에 익히는 단계.
라이브 앱에서 짧은 영상을 GIF로 만들고, 비행기 모드로 전환한 뒤에도 앱이 동작하는지 확인합니다 — 개발자도구 Network 탭에서 "정말 아무것도 안 나가는지"도.
UI에 없는 작업(예: 특정 구간만 모자이크, 워터마크 overlay)을 raw ffmpeg 명령으로 직접 실행해 봅니다 — ffmpeg 문법 연습장으로 활용.
클론 후 server.js로 띄워 crossOriginIsolated가 true인지 콘솔로 확인하고, 헤더를 빼면 멀티스레드 코어가 어떻게 실패하는지 관찰합니다 — COOP/COEP의 동작을 몸으로 익히는 과제.
index.html의 명령 조립 패턴을 따라 새 작업(예: 9:16 세로 변환 + 블러 배경)을 UI 버튼으로 추가하고 PWA 캐시 갱신까지 처리해 봅니다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 앱 사용 + ffmpeg 기본 개념(코덱·컨테이너·CRF) | 라이브 앱 · ffmpeg 입문 자료 |
| 2주차 | ffmpeg.wasm API와 가상 파일시스템 | ffmpeg.wasm 문서 · worker.js |
| 3주차 | 교차 출처 격리 — SAB·COOP/COEP·coi 우회 | 실습 3 · web.dev 격리 가이드 |
| 4주차 | PWA·워커 패턴 + 기능 추가 | 실습 4 · service-worker.js |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| ffmpeg | 영상·오디오 변환의 사실상 표준 CLI 도구. |
| WebAssembly (Wasm) | 브라우저에서 네이티브급 속도로 도는 바이너리 포맷 — C로 짠 ffmpeg을 통째로 이식 가능. |
| SharedArrayBuffer | 스레드 간 공유 메모리 — 멀티스레드 Wasm의 전제. |
| COOP / COEP | 교차 출처 격리 헤더 쌍 — SAB 사용 허가 조건. |
| coi-serviceworker | 정적 호스팅에서 격리 헤더를 후장착하는 서비스워커 우회. |
| PWA | 설치·오프라인이 가능한 웹 앱 표준. |
| CRF | Constant Rate Factor — 18(거의 무손실)~51(최대 압축)의 품질 다이얼. |
| 2-pass 팔레트 | GIF 256색 한계를 위해 최적 팔레트를 먼저 뽑고 적용하는 고품질 기법. |
| atempo | 음정 유지 속도 변경 필터 — 0.5~2 범위라 배속엔 체인 필요. |
| Wake Lock | 처리 중 화면 꺼짐을 막는 브라우저 API. |