mediasense

mediasense

让 Claude 拥有耳朵和眼睛。 Claude 无法自行收听音频或观看视频；借助 mediasense，它就可以了。在 Claude Code 或 Claude Desktop 中，指向一条语音消息、播客、录音或会议内容，或粘贴 TikTok、YouTube 或 Instagram 链接，然后用日常语言提出请求。Claude 随后可以转录内容、总结内容、解释发生了什么、找到某句话出现的时间，或编辑内容。

you: what does this voice message say? ~/Downloads/audio-from-maria.opus
you: summarize this https://www.tiktok.com/@someone/video/7350…
you: what does he show at 0:30? and what tool is he talking about?
you: clean up ~/Desktop/podcast.m4a — remove the "um"s and long pauses
you: make short captions for ~/Videos/reel.mp4
you: put intro.mp3 under the first 5 seconds of talk.mp4, ducked

_{这是一个 17 秒 TikTok 视频的实际输出，视频由 @elim.doc 发布，已获创作者许可。运行 python docs/make_demo.py 可重新生成动画。}

mediasense 在你的电脑上运行：它会下载链接内容，以约 99 种语言转录语音，并为每个词添加时间戳；在场景切换处选取关键帧，然后将转录文本、镜头列表和联系表图像交给 Claude。内容不会上传到任何地方。

Português 🇧🇷

设置

Windows – 在 PowerShell 中粘贴：

irm https://raw.githubusercontent.com/joaoestella/mediasense/main/install.ps1 | iex

macOS / Linux – 在终端中粘贴：

curl -LsSf https://raw.githubusercontent.com/joaoestella/mediasense/main/install.sh | sh

然后完全退出 Claude Desktop（托盘／菜单栏图标 → Quit），再重新打开，并询问 “总结这个视频：”。首次转录时会下载语音模型（约 500 MB）。

irm https://raw.githubusercontent.com/joaoestella/mediasense/main/install.ps1 -OutFile install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

winget install ffmpeg                    # macOS: brew install ffmpeg · Linux: sudo apt install ffmpeg
python -m pip install --user pipx
python -m pipx ensurepath                # then close and reopen the terminal
python -m pipx install "mediasense[all]"
mediasense setup -n                      # preview what setup will change
mediasense setup
mediasense doctor

/plugin install mediasense --marketplace joaoestella/mediasense

{ "mcpServers": { "mediasense": { "command": "uvx", "args": ["mediasense", "mcp"] } } }

• **Claude Desktop：**向 claude_desktop_config.json 添加一项 mcpServers.mediasense （%APPDATA%\Claude\——Microsoft Store 应用使用 %LOCALAPPDATA%\Claude-Data\claude_…\； macOS 上为 ~/Library/Application Support/Claude/，Linux 上为 ~/.config/Claude/；在 Claude Desktop 中打开 Settings → Developer → Edit Config，即可打开应用实际使用的配置文件）。文件中的其他内容都会保留，原文件会备份到同一目录，文件名为 claude_desktop_config.json.<date>.bak。如果文件不是有效的 JSON，安装程序会停止，不会修改文件。
• Claude Code（如果已安装）：运行 claude mcp add --scope user mediasense -- <path>\mediasense mcp。
• 不会更改其他内容。mediasense setup -n 会显示具体更改，但不会实际修改；--desktop 或 --code 可将操作限制为单个应用。撤销方法：从配置文件中删除 mediasense 项，然后运行 claude mcp remove mediasense --scope user。

在 Windows 上通过 pipx 更新时，如果提示文件“正被另一个进程使用”，这是因为 Claude Desktop 仍在运行旧服务：运行 Get-Process mediasense | Stop-Process -Force，然后重新安装（安装脚本会自动执行此操作）。

遇到问题？mediasense doctor 会检查 FFmpeg、语音模型、GPU、链接下载和 Claude 连接。

教 Claude 何时使用它（推荐）

mediasense 附带一个技能：一份简短指南，可让 Claude 在你粘贴视频链接时调用 mediasense，而不是尝试打开网页（TikTok 等网站会拦截这种操作）。

• **Claude Code：**由 mediasense setup 自动安装。
• **Claude Desktop / claude.ai：**下载 mediasense-skill.zip （安装程序也会将其保存到 Downloads/mediasense/），然后在 Claude 中打开 Settings → Skills 并上传。只需操作一次；它会同步到你的所有设备。

注意：Claude Desktop 会将你在聊天中附加的文件发送给模型，而不是发送到你的电脑，因此请给 mediasense 提供链接或文件路径（在 Claude Code 中，你可以将文件拖入终端）。

斜杠命令

该服务会提供现成的提示词。在 Claude Code 中，它们会显示为 /mcp__mediasense__summarize 等。

Claude 可使用的工具

长任务不会触及 Claude 的工具时间限制：如果处理视频超过约 30 秒（例如在 CPU 上处理长视频，或首次运行时下载语音模型），工具会回复“仍在处理中”并显示进度百分比，Claude 会通过 check_job 持续查询，直到任务完成。

所有工具都接受文件路径或链接。链接会下载到 ~/Downloads/mediasense，每个链接仅下载一次，并会重复使用（可通过 MEDIASENSE_HOME 更改路径）。

命令行

无需 Claude 也能完成所有操作：

mediasense understand "https://youtu.be/…"           # transcript + shots + metadata, as text
mediasense transcribe talk.mp4 -l pt --vocab "Cloudflare, Claude" --also srt
mediasense search talk.transcript.json "next quarter"
mediasense edit talk.mp4 --fillers --silences 0.7 -n   # -n = only show the plan
mediasense edit talk.mp4 --fillers --silences 0.7 --srt --edl --fcpxml
mediasense edit talk.mp4 --cut-between "let me check" "okay so" --cut-range 12:03-12:40
mediasense export talk.transcript.json captions.srt --words-per-cue 2
mediasense place video.mp4 voiceover.wav --at 0:12.5 --mode duck
mediasense storyboard reel.mp4
mediasense fetch "https://www.tiktok.com/@…/video/…"

编辑不会修改原文件：结果会另存为 <name>.edited.* / <name>.placed.*。 EDL 可在 Premiere、Resolve 和 Avid 中打开；FCPXML 可在 Final Cut Pro 和 Resolve 中打开。

须知

• 名称和术语。 Whisper 可能会把 Cloudflare 识别为“Cloud Fair”。使用 --vocab（当 Claude 能从标题或屏幕中推断出名称时，会自动执行此操作）。

• 语气词。 Whisper 往往会省略犹豫语；如果要剪掉这些语气词，请使用 --verbatim。系统会根据语言保护真实词语（例如，“um”在葡萄牙语中是冠词，因此不会被剪掉）。只有将“like”、“tipo”或“né”等含义模糊的词列出来，才会将其删除。

• 速度。 所有操作都能在普通 CPU 上完成：短片段只需几秒，几分钟的音频在默认的 small 模型下大约需要与音频时长相同的时间（base 更快，medium 更准确）。 没有 GPU？使用 --backend openai 可将音频发送到兼容 OpenAI 的转录 API（在任何机器上都很快，但音频会离开你的电脑）。

• NVIDIA GPU（可选，速度快得多）。 安装 CUDA 库后，mediasense 会自动使用 GPU；无需安装 CUDA toolkit：

  python -m pipx inject mediasense nvidia-cublas-cu12 "nvidia-cudnn-cu12>=9,<10" nvidia-cuda-runtime-cu12
  

  （约 1.5 GB；需要支持 CUDA 12 的驱动——mediasense doctor 会检查这两项）。之后请重启 Claude Desktop。

• 词语时间戳为近似值（0.1–0.2 秒）。如需更精确的剪辑和说话人标签，请使用 --backend whisperx（pip install "mediasense[whisperx]"）。

• 从链接下载内容时，请遵守各网站的条款。仅下载你有权下载的内容。

隐私政策

mediasense 完全在你的电脑上运行：无需账户，不含分析功能或遥测，作者也不会收到任何数据。它只会连接互联网以下载你指定的链接、语音模型（首次运行时）、缺失的 FFmpeg，以及——仅当你选择 openai 后端时——将音频发送到你配置的转录 API。结果会保留在你的磁盘上，直到你将其删除。通过 Claude 使用时，工具结果（转录文本、关键帧、元数据）会返回到 Claude 应用，并按照 Anthropic 的隐私政策处理。完整政策：PRIVACY.md。

开发

git clone https://github.com/joaoestella/mediasense && cd mediasense
pip install -e ".[dev,mcp]"
pytest

测试会使用 FFmpeg 构建合成音视频，并调用模拟模型和下载器库，因此无需下载任何内容，几秒内即可完成。欢迎提出想法：为你的语言添加更多语气词、一键安装的 Claude Desktop 扩展（.mcpb），以及 GUI。

发布

1. 在 pyproject.toml、src/mediasense/__init__.py、server.json（两处）和 .claude-plugin/plugin.json 中更新 version，并在 .mcp.json 中更新固定版本 mediasense==X.Y.Z，然后提交。工作流会拒绝与这些版本不匹配的标签。
2. 执行 git tag vX.Y.Z && git push origin vX.Y.Z。Release 工作流会发布到 PyPI、更新 MCP Registry 中的条目，并创建包含 wheel、mediasense-skill.zip 和 mediasense.mcpb 的 GitHub release。

一次性 PyPI 设置（可信发布，无需令牌）：在 pypi.org 上选择 Your account → Publishing → Add a new pending publisher：项目 mediasense，所有者 joaoestella，仓库 mediasense，工作流 release.yml，环境留空。

许可证

MIT