Local Media Helper

Local Media Helper는 Chrome 확장이 처리할 수 없는 고화질 비디오 작업을 로컬에서 대신 해주는 보조 프로그램입니다. 많은 플랫폼이 고화질 영상을 video-only 트랙과 audio-only 트랙으로 분리해(DASH) 제공하는데, 브라우저 확장 단독으로는 두 트랙을 합칠 수 없습니다. helper는 로컬에서 두 트랙을 하나의 MP4로 합친 뒤 Chrome 확장에 돌려줍니다.

데스크톱 앱에 포함되지 않고 별도 Rust CLI로 제공되며, 미디어 다운로드 자체는 Chrome이 사용자의 브라우저 세션으로 수행합니다.

언제 필요한가요?

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 ffmpeg

Debian/Ubuntu:

sudo apt install ffmpeg

Windows에서는 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를 실행하지 않고, 정해진 ffmpeg mux 명령만 사용합니다.
• 한 번에 하나의 mux job만 처리합니다.

문제 해결

연결 확인이 실패함

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에 직접 저장합니다.

다음 단계

• Chrome 확장
• 비디오 다운로드