AI-MediaLens - OpenRouter를 통한 AI 에이전트용 미디어 분석

Cline이 읽을 수 없는 것(비디오, 오디오, PDF 파일)의 격차를 메웁니다. 파일을 OpenRouter API로 직접 전송하면, API가 멀티모달 모델로 라우팅하고 (모든 모델에 대해 PDF를 파싱합니다).

Cline용 MCP 서버, 독립형 CLI, 그리고 임포트 가능한 Python 모듈로 동작합니다 - 모두 하나의 파일에서.

빠른 시작

git clone https://github.com/Alihkhawaher/ai-medialens.git
cd ai-medialens
pip install mcp          # only needed for MCP mode
python openrouter_media.py setup    # configure API key + register in Cline

setup이 대화형으로:

1. OpenRouter 키를 .env에 저장

2. ai-medialens MCP 서버를 Cline의 전역 설정에 등록

Related MCP server: mcp-multivision-server

지원되는 입력 (확장자로 자동 감지)

사용법

CLI

# Full file
python openrouter_media.py video.mp4 -p "Transcribe all spoken Arabic word-for-word"

# Only seconds 5-20 (trimmed locally; ffmpeg auto-downloaded on first use)
python openrouter_media.py video.mp4 -p "What happens here?" --start 5 --end 20

# Different model / explicit key
python openrouter_media.py doc.pdf -p "Summarize" -m z-ai/glm-5.3-flash -k sk-or-v1-...

# Scanned PDF -> real OCR (billed per page by OpenRouter)
python openrouter_media.py scan.pdf -p "Extract all text" --pdf-engine mistral-ocr

# Speech-to-text (works on video files too - audio track extracted locally)
python openrouter_media.py lecture.mp4 --stt --language ar

# SRT subtitles with timestamps
python openrouter_media.py lecture.mp4 --stt --srt > lecture.srt

# Find models that accept video input, with prices
python openrouter_media.py --list-models video

# Preview request shape without sending (no API cost)
python openrouter_media.py video.mp4 -p "test" --dry-run

MCP (Cline에서)

Cline이 도구를 기본적으로 호출합니다:

use_mcp_tool: server=ai-medialens, tool=analyze_media
arguments: { "path": "...", "prompt": "...", "start": "5", "end": "20" }

use_mcp_tool: server=ai-medialens, tool=transcribe_audio
arguments: { "path": "...", "language": "ar", "srt": false }

Python 모듈로

from openrouter_media import analyze
text = analyze("video.mp4", "Transcribe all speech.")
resp = analyze("doc.pdf", "Summarize.", raw=True)

API 키 확인 순서

1. -k/--key 플래그

2. OR_KEY 환경 변수

3. OPENROUTER_API_KEY 환경 변수

4. 스크립트 옆의 .env 파일 (.env.example 참조)

ffmpeg 및 시간 범위 트리밍

--start/--end는 업로드 전에 미디어를 로컬에서 트리밍합니다 (OpenRouter에는 네이티브 범위 매개변수가 없음). ffmpeg는 다음 순서로 확인됩니다:

1. 번들된 bin\ffmpeg.exe (해당 위치에 배치한 경우)

2. %LOCALAPPDATA%\ai-medialens\bin\ffmpeg.exe에 캐시된 복사본

3. PATH의 ffmpeg

4. 자동 다운로드 (~80 MB 정적 빌드, 1회, Windows)

참고: 트리밍은 -c copy를 사용합니다 (빠르지만 키프레임에서 잘립니다; 정확한 절단은 재인코딩이 필요합니다).

모델

기본값: qwen/qwen3.7-flash ($0.03/M 입력, $0.13/M 출력) — 현재 전체 비디오 입력을 지원하는 가장 저렴한 OpenRouter 모델입니다.

기타 좋은 비디오 지원 옵션 (현재 가격은 --list-models video로 확인):

-m / model=을 통해 모든 OpenRouter 모델 슬러그가 작동합니다 — 새로 출시된 모델도 포함됩니다.

PDF 파싱 엔진

PDF는 로컬에서 또는 OpenRouter가 서버 측에서 파싱합니다:

local이 권장됩니다: OpenRouter의 파서 속도 제한에 걸리지 않으며 디지털 및 스캔된 PDF를 모두 추가 비용 없이 처리합니다.

음성-텍스트 변환 (STT)

OpenRouter의 전용 /audio/transcriptions 엔드포인트(Whisper급 모델)를 사용합니다. 기본 모델: openai/whisper-large-v3-turbo. 기타 옵션: openai/gpt-4o-transcribe, openai/gpt-4o-mini-transcribe, microsoft/mai-transcribe-1.5, openai/whisper-large-v3.

파이프라인 강화 (프로덕션 YouTube→자막 시스템에서 얻은 교훈):

• 모든 오디오/비디오 입력 → ffmpeg가 Opus 32kbps/16kHz/모노로 변환 (WAV보다 8배 작음, 모든 공급자가 허용); 비디오 트랙은 제거됨

• 긴 미디어는 자동으로 6분 청크로 분할 (OpenRouter에는 요청당 ~60초 업스트림 타임아웃이 있음)

• 각 청크는 누락된 Ogg EOS 페이지를 추가하기 위해 다시 먹싱됨 (ffmpeg의 세그먼트 먹서는 이를 생략함; OpenRouter의 파서는 이 페이지가 없는 스트림을 거부함)

• --srt는 verbose_json 세그먼트를 통해 타임스탬프가 있는 SRT 자막을 반환하며, 청크 간에 올바르게 오프셋됨

• 참고: whisper-large-v3는 빨라진 오디오에서 깨진 출력을 생성함; mai-transcribe-1.5는 이를 허용함

참고 사항

• 큰 파일은 메모리에서 base64로 인코딩됩니다 - 매우 큰 비디오는 공급자 업로드 제한에 도달할 수 있습니다.

• 비밀은 안전합니다: .env는 gitignore되어 있으며 절대 커밋되지 않습니다.