README.ko.md

AutoFlowCut

🇺🇸 English 🇰🇷 한국어

Google Flow 로그인 또는 내 Gemini / Veo API 키로 이미지/비디오를 대량 생성하고, CapCut / Premiere Pro / Vrew 프로젝트로 원클릭 내보내기하는 데스크톱 앱.

개요

AI 영상, 아직도 한 장면씩 만들고 계신가요?

AutoFlowCut은 AI 영상 제작 전 과정을 자동화합니다. Google Flow 로그인(무료) 또는 내 Gemini / Veo API 키(BYOK)로 이미지와 비디오를 생성하고, 바로 편집 가능한 CapCut · Adobe Premiere Pro · Vrew 프로젝트로 변환합니다. 대본을 가져오고, 비주얼을 생성하고, 씬별로 최적의 미디어를 선택한 뒤, 원클릭으로 내보내세요.

주요 기능

생성 모드 (Flow 로그인 / API 키)

생성 방식을 선택 — 상단 토글로 언제든 전환:

• Flow 로그인 모드 — Google Flow 로그인으로 생성. 초보자 추천, 무료 생성 가능·정액제(상대적으로 저렴). 느림(100장 30분 이상). Google 계정 로그인만 있으면 됨.
• API 키 모드 (BYOK) — 내 Gemini/다른 API 키로 직접 생성. 고급 사용자·대량·빠른 작업. 종량제(현재 무료 없음). 빠름(100장 2~5분).

AI 이미지/비디오 생성

• 일괄 이미지 생성 — 공식 Google GenAI API로 100장 이상의 AI 이미지를 배치 생성. 에러 자동 재시도
• T2V (Text-to-Video) — 텍스트 프롬프트에서 비디오 클립 생성 (Veo 3.1)
• I2V (Image-to-Video) — 생성된 이미지를 비디오로 변환
• 씬별 미디어 선택 — 이미지, T2V, I2V 중 최적 미디어 자동 선택 (우선순위: I2V > T2V > Image)

레퍼런스 시스템

• 캐릭터/배경/스타일 레퍼런스 — 태그 기반 자동 매칭으로 200개 이상 씬에서 시각적 일관성 유지
• 87개 스타일 프리셋 — 애니메이션, 사진, 영화 등 11개 카테고리
• 스타일 프롬프트 자동 주입 — 레퍼런스 스타일이 생성 프롬프트에 자동 합성

내보내기 (CapCut / Premiere Pro / Vrew)

• 멀티 에디터 내보내기 — CapCut, Adobe Premiere Pro(.prproj), Vrew(.vrew)로 원클릭 내보내기
• 완성 프로젝트 — 타임라인, 미디어, 자막, Ken Burns 애니메이션 포함
• 프로젝트 파일 직접 쓰기 — 디스크에 바로 기록 (수동 ZIP/임포트 불필요)
• 자동 실행 + 설치 안내 — 내보내기 후 대상 에디터 자동 실행. 미설치 시 다운로드(또는 스토어) 페이지 안내
• SRT 자막 — 다국어 자막 포함 내보내기

오디오/SFX 통합

• 오디오 패키지 임포트 — 나레이션, 보이스, SFX 파일 자동 인식
• SRT 타임코드 매칭 — 자막 타이밍 기반 오디오 배치
• 멀티 트랙 타임라인 — 이미지/자막/나레이션/보이스/SFX 트랙 + 가로 줌, 스크럽, 플레이헤드
• 그룹 펼치기 — 보이스/SFX는 캐릭터·카테고리별로 접고 펼쳐서 개별 파일 row 확인
• 파일 row 미니 마커 — 각 파일 row에 클립 위치 컬러바 → 스크롤해도 시간 컨텍스트 유지
• 드래그로 타임코드 보정 — 보이스/SFX 클립을 드래그해 시작 시점 조정. 원본 파일은 건드리지 않고 .audio_overrides.json에 보정값만 저장
• 트랙/라벨 크기 조절 — 트랙 높이, 라벨 컬럼 너비 드래그로 조절 (localStorage 저장)
• 프리뷰 패널 — 현재 플레이헤드 위치의 씬 이미지 + SRT 자막 표시
• 키보드 단축키 — Space 재생/정지, Esc 정지 + 처음으로
• 오디오 리뷰 시스템 — 부적합 오디오에 사유 표시 + 일괄 정리

MCP 서버 (Claude Code 연동)

• 내장 MCP 서버 — Claude Code에서 직접 씬/레퍼런스/프롬프트 편집
• HTTP API 브릿지 — 외부 도구 연동 (포트 3210)
• 스킬 시스템 — Claude Code 스킬 설치/관리, 앱 첫 실행 시 자동 설치
• Story Engine v2 — 9-Wave 자동 파이프라인으로 대본부터 내보내기까지 전자동
  • /story-new → 에피소드 초기화 + 주제 논의
  • /story-execute → W1~W9 자동 실행 (서브에이전트 + 리뷰 루프, W3/W7 사용자 게이트 2개)
  • /story-step → 다음 한 웨이브만 실행 후 종료. 수동 모드 — 웨이브 내부 질문 없음. 사용자가 결과물 보고 다음 호출 시점 결정
  • /story-next → 중단 후 재개 (/story-execute 위임)
  • /story-rewrite → 기존 에피소드 개선 (몰입도 진단 → fork → 부분 웨이브 재실행)

기타

• 전체폭 데스크톱 작업공간 — 배치 생성과 내보내기에 집중한 React 쉘
• 다국어 — 한국어, 영어
• 프로젝트 관리 — 여러 프로젝트를 독립 관리, project.json 기반
• 다양한 입력 형식 — TXT, CSV, SRT 파일 가져오기

기술 스택

카테고리	기술
Frontend	React 18 + Vite 6
Desktop	Electron 36
AI Engine	Google Flow (로그인) + Google Gemini / Veo API (BYOK)
Backend	Firebase (Auth, Firestore, Cloud Functions)
MCP	@modelcontextprotocol/sdk
결제	Lemon Squeezy
빌드	electron-builder (DMG, ZIP, NSIS, APPX)
테스트	Vitest

아키텍처

Electron BrowserWindow
├── [React Shell] — 전체폭 데스크톱 앱 (Shell.jsx)
│   ├── Header — 프로젝트 선택, Export, Settings
│   ├── PromptInput — 프롬프트 입력
│   ├── SceneList — 씬 목록 (이미지/비디오/자막)
│   ├── ReferencePanel — 레퍼런스 관리
│   ├── AudioPanel — 오디오/SFX 임포트
│   └── StatusBar — 생성 진행 상태
│
├── [GenAI IPC] — 메인 프로세스의 Gemini / Veo BYOK 호출
│   └── 로컬 암호화 API 키 저장 + REST 클라이언트
│
└── [MCP Server] — stdio + HTTP (포트 3210)
    └── 씬/레퍼런스/스타일/오디오 관리 도구

IPC 네임스페이스

네임스페이스	역할	파일
fs:*	파일 I/O	electron/ipc/filesystem.js
genai:*	Google GenAI API (이미지/비디오 생성)	electron/ipc/genai-api.js
capcut:*	CapCut 경로 감지, 프로젝트 쓰기, 앱 실행	electron/ipc/capcut.js
auth:*	Google OAuth	electron/ipc/auth.js

비디오 생성 파이프라인 (3-Phase Async)

Phase 1: Submit     → 동시 진행 창을 유지하며 여러 비디오 요청 제출
Phase 2: Poll       → 모든 generationId를 병렬 폴링 (최대 20분)
Phase 3: Download   → 완료된 비디오를 순차 다운로드 + 저장

프로젝트 구조

AutoFlowCut/
├── electron/                    # Electron 메인 프로세스
│   ├── main.js                 # 메인 프로세스, 메뉴, IPC 등록
│   ├── preload.js              # Context bridge (window.electronAPI)
│   └── ipc/                    # IPC 핸들러
│       ├── filesystem.js       # 파일 I/O
│       ├── genai-api.js        # Google GenAI API (이미지/비디오 생성)
│       ├── capcut.js           # CapCut 경로 탐지, 프로젝트 쓰기
│       ├── auth.js             # Google OAuth
│       ├── layout.js           # 창/레이아웃 IPC
│       ├── mcp.js              # MCP HTTP 서버 브릿지
│       └── googleApiError.js   # Google API 오류 포맷
│
├── src/                        # React 프론트엔드
│   ├── App.jsx                 # 메인 앱 로직
│   ├── Shell.jsx               # 전체폭 앱 쉘
│   ├── components/             # UI 컴포넌트 (35+)
│   │   ├── Header.jsx
│   │   ├── SceneList.jsx
│   │   ├── ReferencePanel.jsx
│   │   ├── AudioPanel.jsx
│   │   ├── ExportModal.jsx
│   │   ├── SettingsModal.jsx
│   │   ├── SceneDetailModal.jsx
│   │   ├── VideoDetailModal.jsx
│   │   └── ...
│   ├── hooks/                  # React 훅 (15+)
│   │   ├── useGenAPI.js        # Google GenAI API 래퍼 (이미지, 비디오)
│   │   ├── useAutomation.js    # 배치 이미지 생성 파이프라인
│   │   ├── useVideoAutomation.js # 비디오 생성 (3-Phase Async)
│   │   ├── useSceneGeneration.js # 개별 씬 재생성
│   │   ├── useReferenceGeneration.js # 레퍼런스 생성
│   │   ├── useGenerationQueue.js # 통합 생성 큐
│   │   ├── useExport.js        # CapCut 내보내기
│   │   ├── useAudioImport.js   # 오디오 임포트 + SRT 매칭
│   │   ├── useScenes.js        # 씬 상태 관리
│   │   ├── useProjectData.js   # project.json 관리
│   │   └── ...
│   ├── exporters/              # CapCut JSON 생성 + 디스크 쓰기
│   ├── firebase/               # Auth, Firestore, Cloud Functions
│   ├── contexts/               # AuthContext
│   ├── config/                 # 기본값, 스타일 프리셋 (87개)
│   ├── locales/                # ko, en
│   ├── utils/                  # 유틸리티 (파서, 태그 매칭 등)
│   └── stripe/                 # 결제 (Lemon Squeezy)
│
├── mcp-server/                 # MCP 서버 (Claude Code 연동)
│   └── index.js                # 씬/레퍼런스/스타일/오디오/스킬 도구
│
├── skills/                     # Claude Code 스킬
│   ├── story-engine/           # Story Engine v2 (9-Wave 파이프라인)
│   ├── story-new/              # /story-new 에피소드 초기화
│   ├── story-execute/          # /story-execute W1~W9 자동 실행
│   ├── story-next/             # /story-next 재개
│   ├── story-step/             # /story-step 단일 웨이브 수동 실행
│   └── story-rewrite/          # /story-rewrite 에피소드 개선
├── docs/                       # 문서 (스키마, 스토어 설명 등)
├── tests/                      # Vitest 단위/통합 테스트 (src/ 구조 미러링)
├── scripts/                    # 빌드 헬퍼 (electron 이름 패치, 빌드 번호 bump 등)
├── assets/                     # 앱 아이콘 (icon.icns, icon.png)
├── public/                     # 정적 에셋 (스타일 썸네일)
├── vite.config.js
└── package.json

시작하기

요구사항

• Node.js 18+
• npm
• Google 계정 + Google API 키 (Gemini / Veo 접근용)
• CapCut 데스크톱 앱

설치

git clone https://github.com/touchizen/AutoFlowCut.git
cd AutoFlowCut
npm install

개발

# 개발 모드 (test 환경 — _test GCF 사용)
npm run dev

# 개발 모드 (prod 환경 — _prod GCF 사용)
npm run dev:prod

빌드

# macOS 배포 (DMG + ZIP, 코드 서명 + 공증)
npm run dist:mac

# Windows 배포 (NSIS + ZIP + APPX, Certum OV 코드 서명)
npm run dist:win

# Windows 개별 타겟
npm run dist:win:nsis    # 웹사이트 다운로드용 (.exe, 코드 서명)
npm run dist:win:appx    # MS Store용 (.appx)

# Linux 배포 (AppImage + deb)
npm run dist:linux

# 테스트 환경 배포
npm run dist:test:mac
npm run dist:test:win

# 패키징 테스트 (설치 파일 없이)
npm run pack

Windows 코드 서명: SimplySign Desktop이 연결된 상태에서 빌드하면 자동 서명됩니다 (Certum OV 인증서).

빌드 결과물은 release/ 디렉토리에 생성됩니다.

테스트

npm test              # watch 모드
npm run test:run      # 1회 실행
npm run test:coverage # 커버리지 리포트

테스트 파일은 tests/ 디렉토리 안에 있고 src/ 구조를 미러링합니다 (Vitest + jsdom + @testing-library/react).

환경 분리 (test / prod)

Cloud Functions는 _test / _prod 접미사로 분리 배포되어 있습니다.

스크립트	환경	GCF 접미사
npm run dev	test	_test
npm run dev:prod	prod	_prod
npm run dist:mac / dist:win	prod	_prod
npm run dist:test:mac / dist:test:win	test	_test

사용 방법

1. AutoFlowCut에 로그인한 뒤 Settings에서 Google API 키 입력
2. 프롬프트 입력 (텍스트 / CSV / SRT 가져오기)
3. 레퍼런스 이미지 설정 (캐릭터, 배경, 스타일 태그)
4. 이미지 생성 → 내 Google API 키로 배치 생성 시작
5. (선택) 비디오 생성 → T2V 또는 I2V
6. Export → AutoFlowCut 체험판/구독 상태 확인 후 CapCut 프로젝트 폴더에 자동 저장 → CapCut 실행

MCP 서버

Claude Code에서 AutoFlowCut의 씬/레퍼런스/프롬프트를 직접 편집할 수 있습니다.

주요 도구

도구	설명
load_csv	CSV 파일 + 이미지 로드
list_scenes / get_scene	씬 조회
update_prompt / batch_update_prompts	프롬프트 수정
list_references / update_reference_prompt	레퍼런스 관리
list_problem_scenes	문제 씬 필터링
list_styles	스타일 프리셋 조회
export_capcut	CapCut 내보내기
install_skill / list_skills	스킬 관리
get_progress	W_progress.json 읽기 (진행 상태는 subagent가 파일 I/O로 직접 기록)
app_generate_scene / app_start_scene_batch	앱 연동 생성

HTTP API

설정에서 HTTP 서버 활성화 시 (기본 포트 3210):

GET  /api/current-project  — 현재 프로젝트 상태
GET  /api/scenes           — 씬 조회
GET  /api/references       — 레퍼런스 조회
POST /api/update           — 씬/레퍼런스 수정
POST /api/generate-scene   — 개별 씬 이미지 생성
POST /api/generate-reference — 개별 레퍼런스 이미지 생성
POST /api/start-scene-batch — 씬 일괄 생성 시작
POST /api/start-ref-batch  — 레퍼런스 일괄 생성 시작
GET  /api/batch-status     — 배치 진행 상태 조회

다운로드

• macOS / Windows: GitHub Releases
• Windows (MS Store): Microsoft Store

링크

• 홈페이지: touchizen.com
• Youtube: @터치즌
• Discord: touchizen
• 문의: gordon.ahn@touchizen.com

기여 & 보상

AutoFlowCut에 대한 커뮤니티 기여에 적극적으로 보상합니다.

🐞 버그 수정 → 사용 크레딧

앱의 버그를 찾아 수정하고 PR을 보내주세요. 리뷰 후 머지되면 기여도 평가에 따라 사용 크레딧을 드립니다 — 최소 10회 생성부터 1년 무제한 사용까지.

🔌 수익모델 플러그인 → 머지

수익 모델을 더하는 플러그인을 개발하셨나요? PR을 보내주세요. 프로젝트에 맞고 안전하게 만들어진 플러그인은 리뷰 후 머지하고 세부 사항을 함께 조율합니다.

PR을 열거나 Discord에서 논의를 시작하세요. 모든 기여는 AGPL v3 로 받습니다 — CONTRIBUTING.md 참고. 보상 규모는 각 기여의 품질과 영향도에 따라 메인테이너 재량으로 지급됩니다.

라이선스

Copyright (C) 2026 Touchizen

본 프로그램은 자유 소프트웨어입니다. GNU Affero General Public License v3 조건에 따라 자유롭게 사용·수정·재배포할 수 있습니다. 전체 라이선스 텍스트는 LICENSE 파일을 참고하세요.

요약: 자유롭게 사용·수정·자가 호스팅 가능. 단, 수정본을 배포하거나 수정본으로 네트워크 서비스를 운영하는 경우, 변경 사항도 AGPL v3 로 공개해야 합니다.

기여는 동일한 AGPL v3 라이선스로 받습니다 — CONTRIBUTING.md 참고.

---

면책: 이 앱은 Touchizen에서 독립적으로 개발한 제품으로, Google 또는 ByteDance(CapCut)와 제휴·후원·인증 관계가 없습니다.