Local Media Helper
Local Media Helper는 사용자 Mac에서 동작하는 보조 프로그램으로, Chrome 확장 단독으로는 불가능한 두 가지 일을 대신합니다.
미디어 합치기(mux). 많은 플랫폼이 고화질 영상을 video-only 트랙과 audio-only 트랙으로 분리해(DASH) 제공하는데, 브라우저 확장 단독으로는 두 트랙을 합칠 수 없습니다. helper는 로컬에서 두 트랙을 하나의 MP4로 합친 뒤 Chrome 확장에 돌려줍니다. 다운로드 자체는 여전히 Chrome이 사용자의 브라우저 세션으로 수행하고, helper는 합치는 일만 합니다.
AI 채팅 브리지. 리더 모드에서 지금 읽는 글을 두고 Claude Code와 대화할 수 있는데, 그 CLI를 실행하고 답변을 흘려보내 주는 것이 helper입니다. 글 내용도, 질문도, 답변도 전부 사용자 Mac 안에 머뭅니다.
데스크톱 앱에 포함되지 않고 별도 Rust CLI로 제공됩니다.
언제 필요한가요?
리더 모드 AI 채팅 (필수)
- 리더 모드의 AI 채팅은 helper가 설치·페어링된 상태에서만 열립니다.
- Claude Code CLI도 설치되어 있고 로그인되어 있어야 합니다 — AI CLI 설정 참고.
- 현재는 macOS 전용입니다.
TikTok 클립 (필수인 경우 있음)
- 많은 TikTok 영상이 audio/video 분리 스트림으로 제공됩니다. 이런 영상을 Clip to Obsidian으로 저장하려면 helper가 필수입니다. helper가 없으면 팝업이 "This TikTok video needs the Local Media Helper" 안내와 함께 클립을 중단합니다.
- progressive(단일 파일) 영상은 helper 없이도 클립됩니다.
Facebook 릴 클립 (선택)
- audio/video가 분리된 Facebook 릴은 helper가 있으면 소리가 포함된 하나의 MP4로 저장됩니다. helper가 없으면 클립은 계속 진행되지만 영상만 있는(무음) 파일로 저장됩니다.
Instagram → Immich 고화질 업로드 (선택)
- Instagram saved posts, my posts, profile grid를 Immich로 업로드할 때 영상 화질을 최대한 보존하고 싶을 때
- Instagram이 고화질 영상을 video-only/audio-only sidecar로 제공하고, 낮은 화질 progressive 영상만 fallback으로 제공할 때
- Immich 서버가 Raspberry Pi처럼 가벼운 장비라 Social Archiver 전용 처리 도구를 올리고 싶지 않을 때
helper가 없어도 Immich 업로드는 계속 동작합니다(낮은 화질 fallback).
설치
macOS에서는 Local Media Helper .pkg installer를 다운로드해 더블클릭으로 설치합니다. 설치가 끝나면 helper 앱, 로그인 시작 항목, Chrome pairing support가 함께 등록됩니다.
설치 후 Chrome 확장 Options에서 Pair Local Helper를 클릭합니다. 수동 token 복사는 일반 설치 흐름에서 필요하지 않습니다.
helper 앱을 직접 열면 설치가 진행되는 것이 아니라 현재 실행 상태와 다음 단계를 보여줍니다.
개발 실행
소스에서 바로 실행:
cd local-media-helper
cargo run -- serve --token local-test-token기본 주소:
http://127.0.0.1:8787로컬에 설치:
cd local-media-helper
cargo install --path .
social-archiver-local-media-helper serve --token local-test-token--token을 생략하면 helper가 임시 pairing token을 생성해 터미널에 출력합니다. 개발 실행 시에는 ffmpeg가 필요할 수 있습니다.
macOS:
brew install ffmpegDebian/Ubuntu:
sudo apt install ffmpegWindows에서는 scoop install ffmpeg 또는 공식 ffmpeg 빌드를 사용할 수 있습니다.
Chrome 확장 설정
Chrome 확장 옵션에서 다음 값을 설정합니다:
Local Media Helper URL: http://127.0.0.1:8787
Pairing Token: Pair Local Helper 버튼으로 자동 설정
Use local helper: on
Prefer helper for high-quality Immich videos: on저장할 때 Chrome이 http://127.0.0.1:8787/* 권한을 요청할 수 있습니다. 허용해야 확장이 helper에 /health와 /media/dash-mux 요청을 보낼 수 있습니다.
로컬 패키지 만들기
개발자가 테스트용 바이너리를 만들 때:
cd local-media-helper
./scripts/package-local.sh생성물은 local-media-helper/dist/ 아래에 만들어집니다. MVP 단계에서는 signed/notarized 앱 패키지가 아니므로, 배포 전에 OS별 보안 경고와 설치 흐름을 별도로 검증해야 합니다.
보안 경계
- helper는 기본적으로
127.0.0.1에만 bind합니다. /media/dash-mux는 bearer token이 있어야 호출할 수 있습니다.- helper는 Instagram cookie, Immich API key, Social Archiver token을 받지 않습니다.
- helper는 임의 shell command를 실행하지 않고, 정해진
ffmpegmux 명령만 사용합니다. - 한 번에 하나의 mux job만 처리합니다.
AI 채팅의 경우:
/ai/*도/media/dash-mux와 같은 bearer token이 있어야 호출할 수 있습니다.- 글 내용은 신뢰할 수 없는 웹 콘텐츠이므로, helper는 Claude Code의 도구를 모두 끈 상태로 실행합니다 — 답변은 하지만 사용자 파일을 읽거나 명령을 실행할 수 없습니다. 빈 임시 디렉터리에서 실행되어 프로젝트 설정이나
CLAUDE.md도 불러오지 않습니다. - 응답이 멈추면 지정된 시간이 지난 뒤 종료되고, 동시에 실행되는 채팅은 최대 2개입니다.
- 대화는 Social Archiver 서버로 전송되지 않습니다. 사용자의 Claude Code 요금제를 사용하고, 로컬 Claude Code 세션 기록에 저장됩니다.
문제 해결
연결 확인이 실패함
helper가 실행 중인지, URL과 token이 확장 설정과 같은지 확인하세요. 포트를 바꿔 실행했다면 확장 설정의 URL도 같이 바꿔야 합니다.
ffmpeg를 찾지 못함
ffmpeg가 PATH에 없으면 실행할 때 경로를 직접 넘깁니다:
social-archiver-local-media-helper serve --token local-test-token --ffmpeg /path/to/ffmpeg영상이 fallback으로 업로드됨
정상 동작일 수 있습니다. helper가 실패하거나 progressive 영상이 충분히 좋다고 판단되면 Chrome 확장은 기존 browser-ready 영상을 Immich로 업로드합니다.
TikTok 클립이 helper를 요구함
해당 TikTok 영상이 audio/video 분리 스트림으로 제공되는 경우입니다. helper를 설치하고 확장 설정에서 활성화한 뒤 다시 클립하세요. 확장 설정에 vault 폴더도 선택되어 있어야 합니다 — TikTok 클립은 합쳐진 영상 파일을 vault에 직접 저장합니다.
AI 채팅이 Claude Code 로그인을 요구함
CLI가 인증에 실패하면 채팅 패널에 Sign in to Claude Code 카드가 나타납니다. Claude Code 업데이트가 저장된 로그인 정보를 지우는 경우가 있고, 그 뒤에도 대화형 CLI는 여전히 로그인된 것처럼 보일 수 있습니다. 그러니 실제로 요청을 보내는 명령으로 확인하세요:
claude -p "say OK"인증 오류가 나오면 터미널에서 claude를 실행하고 /login으로 로그인한 뒤 메시지를 다시 보내세요. 카드의 재확인 버튼은 로그인 여부를 검사하지 못하고 입력창만 다시 열어 줄 뿐이라, 다시 보내는 것이 진짜 확인입니다.