Flucto 문서

빠른 시작

GitHub Releases의 Flucto-<version>-cli-setup.zip을 받아 쓰기 가능한 폴더에 푼다. Windows는 install.cmd, macOS/Linux는 bash install.sh — Node.js나 관리자 권한이 필요 없다. 부트스트랩이 비공개 Node.js 24 런타임을 nodejs.org에서 받아 SHA256을 검증하고, 번들 CLI와 yt-dlp/FFmpeg를 비공개 접두사에 설치한다. 인터넷 연결이 필요하다.

# 압축 해제 후
install.cmd                    # Windows
bash install.sh                # macOS / Linux

# 새 셸에서 점검
flucto doctor --json
flucto setup --json            # 바이너리 수동 설치/갱신

fl 과 flucto 두 이름 모두 등록된다. 단, PowerShell은 fl을 Format-List로 예약하므로 PowerShell에서는 flucto 또는 fl.cmd를 쓴다 — fl은 cmd.exe와 POSIX 셸에서 동작한다. 자막 전용이면 flucto setup --yt-dlp-only --json으로 ffmpeg 다운로드를 생략할 수 있다.

격리 설치: install.ps1 -InstallDir DIR -NoProfile 또는 install.sh --install-dir DIR --no-profile — 영구 PATH 변경 없이 설치. Windows 부트스트랩의 실행 정책은 프로세스 범위라 사용자 정책을 바꾸지 않는다. 이미 Node.js 24가 있다면 npm i -g flucto도 가능하지만 필수는 아니다.

명령어 레퍼런스

모든 명령은 -j(--json)를 지원하며, 사람이 읽는 출력과 기계가 파싱하는 출력이 같은 엔진에서 나온다.

flucto search "<keyword>"        # 12개 사이트 통합 검색
flucto download <url>            # MP4/MP3 다운로드 (d)
flucto batch <file>              # URL 목록 일괄 처리 (b)
flucto transcript <url>          # 자막 → Markdown (t)
flucto md <url>                  # 프론트매터 포함 Markdown (m)
flucto channel to-md <@handle>   # 채널 전체 → Markdown 폴더
flucto info <url>                # 메타데이터 (i)
flucto formats <url>             # 사용 가능한 포맷 (f)
flucto languages <url>           # 자막 언어 목록 (l)
flucto doctor                    # 바이너리 건강 점검 (doc)
flucto setup                     # yt-dlp/ffmpeg 구성 (s)
flucto update check|download|apply

batch 와 channel to-md 는 --out 기준으로 전용 하위 폴더를 만든다(예: notes/handle-channel-md-20260829-…/). 파일이 섞일 일이 없다.

fl transcript vs fl md

• /t(transcript) — 데스크톱 앱과 같은 포맷. 제목/메타데이터/타임스탬프 문단.
• /m(md) — YAML 프론트매터 + 썸네일이 붙은 문서 지향 포맷. 옵시디언·블로그 파이프라인에 적합.

검색

flucto search "<keyword>"는 등록된 12개 사이트(YouTube · X · Reddit · Bilibili · Dailymotion · Niconico · OK.ru · VK Video · Instagram · Threads · TikTok · Vimeo)를 한 번에 검색한다. --platform <site>로 한 사이트만 고를 수 있다. --limit은 사이트별이 아니라 전체 결과 상한(1–50, 기본 20)이다.

flucto search "nature" --limit 20 --json
flucto search "nature" --platform youtube --json
flucto search "初音ミク" --platform nicovideo --json

결과는 native/index 검색 방법과 출처 사이트를 표시하고, 실패한 사이트가 있어도 나머지 결과는 그대로 보인다 — 부분 실패와 빈 검색은 종료 코드 0, 전체 실패는 error와 함께 종료 코드 4다. 데스크톱의 Search videos 기본값은 All sites(통합 검색).

X·Instagram·TikTok·Vimeo 검색, OK.ru·Threads 브라우저 검색과 모든 공개 인덱스 검색 경로는 로컬 Google Chrome(또는 FLUCTO_CHROME_PATH)이 필요하다. Bilibili·VK Video 등도 네이티브 검색이 제한되면 Chrome 기반 폴백을 쓴다. 브라우저 컨텍스트는 임시·익명으로 로그인 프로필을 읽지 않는다. CAPTCHA·지역 제한·유료/비공개 미디어 접근을 우회하지 않는다 — 검색되는 영상도 다운로드 시점에는 삭제·비공개·지역 제한일 수 있다.

글로벌 옵션

Markdown 변환

자막은 JSON3·XML/SRV3·VTT 포맷을 모두 파싱하고, HTML 태그·엔티티를 제거한 뒤 공백 구간(--paragraph-gap)으로 문단을 나눈다. 요청 언어 자막이 없으면 기반 언어 → 원본 ASR → 대체 트랙 순으로 폴백하되 최대 3개까지만 시도하고, 없으면 없다고 정확히 말한다.

# 자막 언어 목록 확인
fl l "https://youtu.be/…" -j

# 한국어 자막을 stdout으로
fl t "https://youtu.be/…" -l ko -s

# 채널 100개를 노트 폴더로
fl channel to-md "@handle" --limit 100 -o ./notes -l ko

rate limit(429)에는 지수 백오프로 저항하고, 반복 실패 시 서킷브레이커가 60초간 열려 SERVICE_UNAVAILABLE을 반환한다. 이때는 쿠키나 프록시를 붙이는 것이 정답이다.

쿠키 · 프록시 · 환경변수

YouTube가 "sign in to confirm you're not a bot" 검사를 걸면 쿠키 또는 프록시가 필요하다. 플래그가 환경변수보다 우선한다.

AI 에이전트 연동

Flucto CLI는 처음부터 에이전트를 전제로 설계됐다. 결과 JSON은 stdout, 진행 이벤트 NDJSON은 stderr — 파이프로 정확히 분리된다.

# 최종 결과만 파싱
fl t "URL" -j 2>/dev/null | jq .filePath

# 진행률 표시하며 실행
fl channel to-md "@handle" -o ./notes --progress-json

종료 코드

에이전트에 이렇게 시켜라: "GitHub 릴리스의 Flucto cli-setup.zip(자체 Node 런타임 포함)으로 Flucto CLI를 설치하고, 이 채널의 최근 영상 자막을 Markdown 노트로 ./notes에 정리해줘: https://youtube.com/@handle"

데스크톱 앱

CLI와 같은 TypeScript 엔진을 GUI로 감싼 것이다. 배치 큐, 포맷 프리셋, 다운로드 히스토리, 12개 사이트 통합 검색, 자막→Markdown 패널을 제공하며 Windows·macOS·Linux 인스톨러는 GitHub Releases에 있다.

• /통합 검색 — 사이트별 결과 개수·native/index 출처·실제 오류를 Search sources에서 확인
• /고급 네트워크 설정 — cookies.txt/프록시를 UI에서 지정 (CLI의 --cookies와 동일 엔진)
• /yt-dlp 자동 갱신 — 공식 nightly 채널을 추적해 추출기가 최신 상태를 유지한다
• /앱 업데이트 — Windows/Linux는 electron-updater; 미서명 macOS는 검증된 DMG를 받아 수동 교체

CLI만 필요하면 앱을 설치할 필요가 없다 — cli-setup.zip이 자체 Node 런타임을 가져온다. 앱 유저가 fl을 쓰고 싶다면 같은 ZIP 또는 npm i -g flucto — 같은 설정·같은 엔진이다.

문제 해결