Claude Code를 사용하여 Electron과 FFmpeg 기반의 크로스 플랫폼 데스크톱 앱인 ClipForge를 3주 만에 아이디어 단계에서 출시까지 완료했습니다.

문제점 (The Problem)

대부분의 비디오 프로세싱 도구는 다음과 같은 사항을 강요합니다:

• 파일을 클라우드에 업로드 (개인정보 보호 문제)
• 파일 크기 제한 문제 해결
• 프리미엄 기능 결제

저는 완전한 로컬 환경에서 작동하며, 기능이 풍부하고, 디자인이 보기 좋은 비디오 프로세싱 도구를 원했습니다. 그래서 ClipForge를 만들었습니다.

ClipForge란 무엇인가? (What is ClipForge?)

ClipForge는 20개 이상의 비디오/오디오 작업을 로컬에서 처리하는 데스크톱 앱입니다:

• 트랜스코드 (Transcode) — MP4, WebM, MKV, MOV, AVI, GIF
• 비주얼 (Visual) — 크롭 (Crop), 워터마크 제거, 회전, 색상 조정, 노이즈 제거 (Denoise)
• 속도 (Speed) — 0.25x에서 4x, 역재생, 부메랑, 루프, 페이드 (Fade)
• 오디오 (Audio) — 추출, 음소거, 볼륨, 정규화 (Normalize)
• 합성 (Composite) — 연결 (Concatenate), 나란히 배치 (Side-by-side), 화면 속 화면 (Picture-in-picture), 오버레이 (Overlay), 자막

세 가지 모드: 단일 작업 (Single operation), 스택 (Stack, 여러 작업을 체인으로 연결), 배치 프로세싱 (Batch processing).

Electron, React, FFmpeg, 그리고 Zustand로 구축되었습니다. Windows, macOS, Linux용으로 제공됩니다.

기술 스택 (The Tech Stack)

계층 (Layer)	기술 (Tech)	이유 (Why)
데스크톱 (Desktop)	Electron 42	크로스 플랫폼, FFmpeg를 위한 Node.js
...

개발 여정 (Development Journey)

1단계: 스캐폴드 (Scaffold)

npm create electron-app clipforge

Electron Forge가 메인 프로세스 (main process), 프리로드 스크립트 (preload script), Vite를 사용하는 렌더러 (renderer) 보일러플레이트를 생성했습니다.

2단계: UI 레이아웃 (UI Layout)

4패널 레이아웃을 구축했습니다:

• 왼쪽: 미디어 풀 (Media pool) + 작업 라이브러리 (Operation library)
• 중앙: 실시간 프리뷰 캔버스 (Real-time preview canvas)
• 오른쪽: 파라미터 인스펙터 (Parameter inspector)
• 하단: 스택/배치 큐 (Stack/Batch queue) + 로그 (Logs)

Tailwind CSS를 사용한 다크 테마입니다.

3단계: FFmpeg 통합 (FFmpeg Integration) — 가장 어려운 부분

이것이 핵심 과제입니다 — FFmpeg의 CLI를 시각적 작업으로 래핑(wrapping)하는 것입니다.

아키텍처 (Architecture):

렌더러 (Renderer, React)
    │  invoke('process:start', request)
    ▼
...

예시: 워터마크 제거 (Watermark Removal)

경계 제한(x≥1, y≥1, 가장자리 지원 불가)이 있는 FFmpeg의 delogo 필터 대신, 저는 크롭 (crop) + 블러 (blur) + 오버레이 (overlay) 방식을 사용했습니다:

case 'delogo': {
  const x = Math.max(0, Math.round(Number(p.x) || 0));
  const y = Math.max(0, Math.round(Number(p.y) || 0));
...

필터 그래프 (Filter graph):

1. crop — 워터마크 영역 추출
2. gblur — 가우시안 블러 (Gaussian blur) (boxblur보다 더 자연스러움)
3. colorchannelmixer=aa=0.7 — 부드러운 통합을 위한 반투명 블렌딩 (semi-transparent blend)

4단계: 실시간 미리보기 (Real-time Preview)

사용자는 프로세싱이 완료된 후가 아니라, 변경 사항을 즉시 확인해야 합니다.

해결책: Canvas 기반의 미리보기 시뮬레이션. FFmpeg를 실행하는 대신, <video> 요소에서 프레임을 읽어 <canvas>에 연산을 적용합니다:

useEffect(() => {
  const render = () => {
    drawPreview(ctx, video, previewOps, { width: rect.width, height: rect.height });
...

밝기 (brightness), 크롭 (crop) 영역, 또는 회전 (rotation)을 조정하면 즉각적인 피드백이 나타납니다.

5단계: 마우스 영역 선택 (Mouse Region Selection)

워터마크 제거를 위해 사용자는 드래그하여 영역을 선택합니다. 화면 좌표는 비디오 픽셀 좌표로 변환되어야 합니다 (레터박스 스케일링 (letterbox scaling) 고려):

function screenToVideo(localX, localY, container, videoW, videoH) {
  const { scale, ox, oy } = getVideoMapping(container, videoW, videoH);
  return {
...

직면했던 버그: onUp 콜백이 useState로부터 오래된 상태 (stale state)를 캡처했습니다. 드래그 중 실시간 좌표를 위해 useRef를 사용하여 수정했습니다.

6단계: 패키징 및 CI/CD (Packaging & CI/CD)

Electron 패키징은 까다롭습니다. FFmpeg 바이너리는 asar 아카이브 안에 들어갈 수 없으며, Linux는 소문자 실행 파일 이름이 필요합니다.

forge.config.ts:

packagerConfig: {
  asar: { unpackDir: 'src/main/ffmpeg' },
  extraResource: ['src/main/ffmpeg'],
...

GitHub Actions는 세 가지 플랫폼을 병렬로 빌드합니다:

jobs:
  build:
    strategy:
...

태그 (tag) 푸시 → 자동 빌드 → GitHub Releases로 자동 배포.

교훈 (Lessons Learned)

AI 코딩은 "코딩을 안 하는 것"이 아니라 "효율적인 코딩"이다

Claude Code가 지루한 작업들 (Electron 패키징, FFmpeg 인자 매핑 (arg mapping), IPC 보일러플레이트 (boilerplate))을 처리해주었지만, 저는 여전히 다음과 같은 작업들이 필요했습니다:

• 아키텍처 결정 (Architectural decisions) 수행
• 생성된 코드 검토 (Review generated code)
• 엣지 케이스 (Edge cases) 디버깅 (stale closures, 경계 조건 (boundary conditions))

핵심 흐름(Core Flow) 우선 구현

미리보기 (preview), 배치 모드 (batch mode), 또는 국제화 (i18n)를 추가하기 전에 "파일 열기 → 작업 선택 → 프로세싱 → 출력" 과정을 먼저 작동하도록 만들었습니다.

패키징은 마지막 지뢰밭

바이너리 파일 (Binary files), asar 압축 (asar compression), 플랫폼별 명명 규칙 (platform-specific naming) 등 — 이 단계에서 많은 시간을 소비하게 될 것을 예상하십시오. 초기 단계부터 CI를 통해 자동화하십시오.

결과

• 3주간의 파트타임 작업
• 6개 카테고리에 걸친 20개 이상의 작업 (operations)
• 3개 플랫폼 지원
• 완전한 로컬 프로세싱 (Fully local processing)
• 오픈 소스: github.com/mayu888/clipforge

라이선스: MIT + Commons Clause (개인적 사용은 무료이며, 상업적 사용은 승인이 필요합니다).

향후 계획

• 패널 간 드래그 앤 드롭 (Drag-and-drop) 작업
• 더 많은 필터 효과 (LUTs, 안정화 (stabilization))
• 커스텀 작업을 위한 플러그인 시스템 (Plugin system)

Electron, FFmpeg, 그리고 AI의 많은 도움을 받아 구축되었습니다. 인디 개발의 미래가 여기에 있습니다.

electron #ffmpeg #react #typescript #ai-coding #desktop-app #video-processing #indie-hacker