Content

Content

将 URL、文件和文本转化为媒体、知识和文档。

一个可自托管的引擎。用于 YouTube 的 HomeTube 客户端——用于其他一切的 Content Studio——HomeTube 浏览器扩展——MCP 服务——CLI——类型化 SDK——REST API，为所有客户端提供支持

快速开始 · HomeTube · 从 HomeTube 迁移？ · 所有客户端 · 连接 Agent · 阅读文档

Content 是一个可自托管的引擎，可将支持的来源转化为媒体、 转录文本、摘要、翻译、图片、元数据、Markdown、PDF 等内容。 后端会分析每个来源，确定实际可生成的内容，规划并运行任务、 记录任务历史并交付结果。

其他所有部分都是同一公开接口的客户端：面向专注 YouTube 体验的 HomeTube、面向通用工作流的 Content Studio、用于当前标签页的 Chromium 扩展、面向 Agent 的 content-mcp 服务、用于终端和 cron 的 CLI、供应用使用的类型化 Python SDK、面向其他所有语言的 REST API，以及用于查看引擎运行情况的 Content Console。可任选一个或多个——它们都不是其他客户端必须经过的中间层，也不包含自己的业务逻辑。

HomeTube 是最快了解其工作方式的途径：粘贴 YouTube URL，选择所需内容，然后看着文件进入资料库。

_{Content 中的 HomeTube — 粘贴 YouTube URL，选择所需内容， 跟踪任务，直到文件进入资料库。了解更多 HomeTube 信息 ↓}

快速开始

Docker Compose 是唯一的运行时前置条件。直接从已发布的镜像安装，无需克隆或构建：

mkdir content && cd content
curl -fsSLO https://raw.githubusercontent.com/LatentNoise/content/main/deploy/docker-compose.yml
curl -fsSL -o .env https://raw.githubusercontent.com/LatentNoise/content/main/.env.example
docker compose up -d

默认的 .env 会启动完整的本地堆栈：

通用工作流请打开 Content Studio；如果来源是 YouTube，则打开 HomeTube。你也可以完全跳过这两个 Web 应用，改用 MCP 服务、命令行、SDK、扩展或 REST API 驱动同一引擎。

所有内容都保留在安装文件夹中：./data 存放数据库、任务和产物；处理完成的文件会送至 ./playground/output。也可以在 .env 中设置 CONTENT_DELIVERY_DIR_HOST，指向你自己的 NAS 或媒体库，其子文件夹随后会成为客户端提供的目标位置选项。

之后更新时运行：

curl -fsSLO https://raw.githubusercontent.com/LatentNoise/content/main/deploy/docker-compose.yml
docker compose pull && docker compose up -d

第一行不可省略，而且最容易被跳过。 docker compose pull 会刷新镜像；堆栈定义是你第一天下载的本地副本，新设置会添加到这个文件中——容器只会接收其 environment: 块中列出的设置。因此，如果 compose 文件仍是最初的版本，就会一直悄悄丢弃此后添加的所有设置，无论你在 .env 中写得多么正确。你的 .env 属于你自己，不会被修改；需要新选项时，请将其与最新版 .env.example 对照。

git clone https://github.com/LatentNoise/content.git
cd content
cp .env.example .env
docker compose up -d --build

一个来源，多种产物

同一引擎可支持媒体和文档工作流：

                             ┌─ My Conference.mp4
                             ├─ My Conference - audio.opus
YouTube URL ──→ Content ─────┼─ My Conference - subtitles - en.srt
                             ├─ My Conference - subtitles - fr.srt
                             ├─ My Conference - transcript.txt
                             ├─ My Conference - summary.md
                             └─ My Conference - summary.pdf

Web page / text / .md file ──→ Content ──┬─ Article.txt
                                         ├─ Article - summary.md
                                         ├─ Article - translation.md
                                         └─ Article.pdf

每个分支都从声明式请求开始。你描述所需结果；Content 会判断可行方案、规划工作、运行可用工具，并记录每个产物的来源。客户端无需处理 yt-dlp 参数、ffmpeg 流水线、转录衔接代码或大模型编排。

客户端

一个引擎，一个契约，多个彼此独立的入口。下方的每个客户端都使用相同的 GenerationRequest，看到相同的已解析能力，并生成相同的产物——它们在使用体验上有所不同，而非在可请求的内容上有所不同。HomeTube 完全可选；其他每一项也是如此。

HomeTube — 专注于 YouTube

http://localhost:8501 · README

粘贴 URL，选择媒体和相关产物，然后跟踪任务，将结果送入媒体库——这正是本页顶部演示的工作流。

在 Content 中使用 HomeTube，你可以：

• 将视频或播放列表下载为视频或音频，并选择画质、编解码器、容器、音频语言和字幕；
• 使用 SponsorBlock 移除或标记赞助片段、剪辑片段、使用服务端 Cookie 凭据，以及嵌入字幕、章节、缩略图和元数据；
• 为每个产物指定易读的名称，并将其送入由 Plex、Jellyfin 或 Emby 监视的文件系统媒体库；
• 在所需运行器可用时，从同一来源获取转录文本、摘要、缩略图或元数据，而不只是下载媒体。

HomeTube 有意保持专注：它不接受文件、上传内容或内联文本作为来源，也不提供更广泛的文档工作流或 PDF 输出。对于这些需求，请使用 Content Studio、API、CLI 或 SDK。HomeTube 是 Content 的一个客户端，并非每个 Content 用户都必须经过的中间层。

它没有自己的设置。 它读取引擎的配置，因此 HomeTube 的设置需在 docker-compose.yml 旁边的 .env 文件中修改：用于存放产物的媒体库（其子文件夹会成为目标选项，CONTENT_DELIVERY_DIR_HOST）、预先选定的音频和字幕语言（CONTENT_LANGUAGE_PRIMARY、CONTENT_LANGUAGES_SECONDARIES、CONTENT_VO_FIRST、CONTENT_LANGUAGE_PRIMARY_INCLUDED_IN_SUBTITLES），以及用于解锁年龄限制或仅限会员观看视频的服务端 Cookie 文件（CONTENT_CREDENTIALS — HomeTube 只会显示其 id；该文件绝不会离开服务端）。如果来源不提供某项选项，则绝不会预先选中；任何默认选项也都不是最终选择。

HomeTube 的 README 记录了每个变量，并通过一个具体示例说明语言规则——一场日语演讲、一位说法语的演讲者，以及最终恰好哪些选项会被预先勾选。完整变量表 列出了引擎接受的所有变量。

从独立版 HomeTube 迁移？

HomeTube——这款独立的 Streamlit 应用——会继续运行并持续维护。一切照常，不设截止日期。后续工作将围绕 Content 展开，因此你可以等准备好时再迁移，而不是被迫迁移。

迁移后保留的功能。 你熟悉的工作流：粘贴 URL，选择质量、编解码器、容器、音频语言和字幕；使用 SponsorBlock 移除或标记赞助片段；剪辑片段；通过服务端 Cookie 文件解锁受限视频；嵌入字幕、章节、缩略图和元数据；并生成易读的文件名，保存到由 Plex、Jellyfin 或 Emby 监视的媒体库中。播放列表也能处理——系统会单独分析并规划每个条目、按条目命名，并将其作为独立文件交付。

新增功能。 同一来源现在还可以生成转录文本、摘要、翻译、生成的缩略图、元数据、Markdown 或 PDF。引擎也不再只能通过 Web 表单访问：Studio、Chromium 扩展、MCP Agent、命令行、SDK 和纯 HTTP 都能请求相同的内容。

尚未迁移的功能。 HomeTube 的播放列表同步功能——通过规划／应用差异，让本地文件夹随时间与播放列表保持同步（检测重命名、归档或删除已移除的视频，以及在命名或位置变更后重新定位）——目前尚不存在。Content 可以下载播放列表，但还不能重新同步播放列表。该功能已列入 M2 路线图。如果播放列表同步是你的主要用途，请继续使用独立版 HomeTube 来完成这项工作。

一条实用提示。 两款 HomeTube 应用默认都使用端口 8501。如果你想同时运行两者，请在 .env 中更改其中一个应用的端口。

Content Studio——完整的请求规范，以表单形式呈现

http://localhost:8502 · README

通用 Web 应用：一次请求可包含多个来源，并支持引擎能够处理的所有输出类型，以及相应的选项、偏好设置和限制。表单由功能能力驱动——它会根据 /capabilities 对你的来源给出的回答来呈现，因此引擎新增的功能无需发布 UI 更新即可显示；无法生成的内容也会显示服务端给出的原因，而不是悄然消失。

_{Content Studio — 构建通用的 URL、文件、上传和文本请求}

Studio 支持通过两种方式处理文件；如果引擎运行在另一台机器上，这两种方式的区别就很重要：

• 从此设备上传——将文件字节发送到引擎，并作为 upload 来源处理（ADR 0020）。一次上传多个文件会生成多个来源。Streamlit 会在 UI 容器中缓冲上传文件，因此这里的上限会刻意设置得低于 API 上限（默认 200 MB；文件选择器会显示当前上限，不会让你在上传失败后才发现限制）。
• 位于服务器上——指定引擎已经可以读取的路径，且该路径必须位于已配置的允许输入根目录下。使用此 Compose 配置时，该根目录为 ./playground/input。

对于真正的大文件，请跳过浏览器：SDK 会通过 client.upload_file(path) 从磁盘流式上传。

Chromium 扩展 — 就在当前标签页中操作

README · 最新版本

无需打开界面，即可将正在观看的页面发送到引擎。仅支持 Chromium 的 Manifest V3（Chrome、Brave、Edge、Vivaldi、Opera、Arc……），无需构建步骤 — 浏览器加载的内容与 zip 中的文件完全一致：

1. 从最新版本下载 content-browser-extension-chromium-v<version>.zip 并解压（Chromium 加载的是文件夹，而不是 zip）；
2. 打开 chrome://extensions，开启开发者模式，点击加载已解压的扩展程序，然后选择文件夹；
3. 打开视频并点击扩展程序。

它会规范化标签页的 URL（youtu.be、Shorts 和嵌入视频都会转换为规范的观看 URL；观看 URL 中的 list= 表示该视频，而不是播放列表），询问引擎该来源可以生成什么，并且只提供相应选项；使用命名引擎自己的建议预填名称；提供资料库中已有的文件夹以及*新建文件夹……*选项；然后跟踪任务，并显示每个文件的存放位置。所有网络请求都在 service worker 中执行 — 引擎默认不会发送 CORS 标头，因此扩展程序无需任何配置即可连接标准实例 （ADR 0016）。

_{浏览器扩展程序 — 直接从当前标签页将其发送到 Content}

弹出窗口的页脚始终会显示它所连接的引擎，因此“我的视频会发送到哪里？”一目了然。其 README 还附有一份如实呈现的逐路径验证表 — 哪些路径已在浏览器中实际运行过，哪些尚未运行。

MCP 服务 — 面向 Agent 和 IDE

README · content-mcp on PyPI

Content 为兼容 MCP 的 Agent 提供了一种受控方式，可将 URL 转换为实际产物，而不只是讨论它们。官方 content-mcp 服务提供的是意图级工具——而非每个端点对应一个工具——用于：

• 分析 URL 并发现它能生成什么；
• 请求一个或多个输出，并选择库中的保存位置；
• 监控任务、取消任务并报告可采取行动的错误；
• 查找产物及其交付路径；
• 在模型上下文之外保留大型媒体文件，同时以内联方式读取小型文本产物。

Agent 无需访问 shell、了解 yt-dlp 语法或掌握后端内部机制。

无需安装。 uvx 会在首次使用时获取服务并将其缓存，因此整个生命周期由客户端负责（更新仍需显式操作——uvx --refresh，或固定为 [email protected]）：

# Claude Code
claude mcp add content \
  --env CONTENT_API_URL=http://localhost:8010 \
  -- uvx content-mcp

适用于 Claude Desktop、Cursor 及其他采用标准 JSON 格式的 MCP 客户端：

{
  "mcpServers": {
    "content": {
      "command": "uvx",
      "args": ["content-mcp"],
      "env": { "CONTENT_API_URL": "http://localhost:8010" }
    }
  }
}

想在 PATH 上使用固定的可执行文件——例如用于离线机器，或控制版本变更时机？请安装它并直接指定名称（"command": "content-mcp"，或在 Claude Code 中使用 -- content-mcp）：

uv tool install content-mcp      # or: pipx install content-mcp

然后自然地提出请求：

分析这段讲座，将音频保存到 Talks，如果可用的运行器支持，则创建文字稿和结构化摘要，并告诉我每个产物保存在哪里。

常见的工具调用流程为 get_config → analyze_source → generate → get_job → get_artifact。下载到 Agent 自己机器上的文件受一个变量限制（默认值为 ~/Downloads/Content，变量名为 CONTENT_MCP_DOWNLOAD_DIR）：如果目标位置超出此范围，操作会被拒绝，而不是调整到范围内——是否扩大范围由操作人员决定，提示词无法说服服务放宽限制。

简要说明它能做什么、不能做什么——MCP 指南包含完整的三张表，其中每一行都经过验证：通过 stdio 对运行中的引擎实际调用得出，而非推断：

CLI — 终端、脚本和 cron

README · PyPI 上的 content-cli

uv tool install content-cli
export CONTENT_API_URL=http://nas.local:8010

content analyze "https://www.youtube.com/watch?v=…"
content video "https://…" --height 1080 --subs en,fr --watch
content audio "https://…" --format opus --playlist --watch
content submit request.json --watch          # a raw GenerationRequest, or -
content jobs ; content job <id> ; content artifacts <id>
content download <artifact_id> -o out.mkv

--watch 会跟踪作业的事件流，而不是反复查询作业状态；退出码会传达执行结果，因此脚本可以据此串联操作 (ADR 0021)： 0 表示成功，2 表示部分成功，1 表示失败或已取消。2 是特意设定的独立状态——播放列表获取到 6 个视频中的 5 个，并不算失败；但如果脚本将其视为成功，就会悄无声息地继续执行，留下缺失的文件。

Python SDK — 支持类型、同步和异步

README · PyPI 上的 content-sdk

唯一的官方 API 客户端：CLI、MCP 服务和 Web 应用都通过它进行通信，因此引擎的规则不会重复实现。仅依赖 Python 3.11+、httpx 和 pydantic。

from content_sdk import ContentClient, outputs

with ContentClient("http://localhost:8010") as client:
    analysis = client.analyze(outputs.url_source("https://www.youtube.com/watch?v=…"))
    job = client.generate(analysis.id, [outputs.audio_output()])
    job.wait()
    for artifact in job.artifacts:
        print(artifact.display_filename, artifact.delivered_path)

AsyncContentClient 涵盖相同的全部功能。分析可通过 ID 访问，因此每次调用都接受 analysis_id 或内联来源 (ADR 0014)； client.upload_file(path) 会将本地文件流式传输到引擎，并返回可直接使用的来源；每个非 2xx 响应都会转换为携带稳定错误代码（NotFound、Gone、ValidationError）的类型化异常。

REST API — 适用于其他所有语言

公开契约 · Swagger 地址：http://localhost:8010/docs

/api/v1 是上述所有客户端所基于的契约，也足够稳定，适合据此构建第九个客户端：请求描述的是期望的输出，而非技术操作；错误代码是不会变化的机器标识符（只有面向人的消息会变化）；而 “有效但尚未实现” 与 “无效” 是两种不同且明确的响应。对于保留字段，API 会拒绝请求，而不是静默忽略。V1 API 没有内置身份验证——请参阅部署与安全。

Content Console — 观察并操控引擎

http://localhost:8503 · README

运维控制台：严格用于观察和控制，不能用于创建下载（这由 Studio 和 HomeTube 负责）。

_{Content Console — 观察并操控引擎}

• 概览 — 版本、缓存、并发数、分析 TTL、实时作业动态、已安装运行器及其可用状态、存储路径。
• 环境 — 每个 CONTENT_* 变量及其生效值、该值是已设置还是回退到默认值，以及一行说明。 从不显示机密信息，只显示其是否存在及其长度。
• 作业 — 可筛选的列表及完整详情：步骤、已提交的 GenerationRequest、带来源信息的产物、有序事件、每个步骤的日志、取消和重试；还可选择启用 5 秒自动刷新，该功能仅在作业正在执行时轮询。
• 存储与缓存，以及包含架构、Swagger、ReDoc 和原始 API 测试器的契约与 API选项卡。

Content 可以生成什么

Content 会解析每个已分析资源和已安装运行器的可用性。客户端会展示实际可生成的内容，而不是列出静态清单，然后在任务进行到一半时失败。

媒体获取支持 YouTube 和 yt-dlp 支持的站点。播放列表可在单个可追踪任务中为每个条目生成制品。完成的文件可直接写入任何已挂载的文件系统媒体库，包括 Plex、Jellyfin 或 Emby 监视的文件夹。

本地和可选 AI 运行器

Content 不依赖任何强制云服务。只要有兼容的运行器可用，即可启用 AI 驱动的输出：

• **摘要、翻译和衍生章节：**连接本地 Ollama 实例，或明确配置 Anthropic 或 OpenAI API 密钥。可按请求排除云端运行器。
• **音频转录：**在引擎旁运行语音服务——执行 docker compose --profile speech up -d 并设置 CONTENT_SPEECH_URL=http://speech:8000，或在 Helm chart 中设置 speech.enabled: true。该服务使用 OpenAI 音频 API，底层为 speaches，同一容器也支持文本转语音。音频只会发送到专用网络上的服务。转录现有字幕无需使用该服务。

可选运行器不可用不会导致 Content 状态异常。受影响的能力会报告为不可用，无法执行的请求会在任务启动前被拒绝。完整列表请参阅部署和配置。

为什么基于 Content 构建？

• **声明意图，而非工具。**请求描述的是输出；yt-dlp、ffmpeg、Whisper、大模型和 PDF 渲染器都只是可替换的实现细节。
• **可自托管，本地优先。**可在工作站、NAS 或家庭实验室中运行。无需账户，不收集遥测数据，也不依赖强制云服务。
• **统一的公共契约。**Studio、HomeTube、MCP、命令行、SDK、扩展程序和 REST API 都基于同一领域模型，而不是各自发展成并行的功能集。
• **面向用户的文件，而非流水线残留物。**引擎会为每个制品命名，并可直接将其放入你正在使用的媒体库。
• **工作过程可观测。**任务会公开状态、有序事件、进度、日志、制品、来源信息、取消和重试。
• 如实报告能力。“有效但不受支持”“此来源不可用”和“已损坏”是不同情况，系统会在正确的阶段之前或期间报告。

工作原理

公开请求描述期望的输出，不规定技术操作：

Sources → Analysis → Capabilities → Execution plan → Job → Artifacts

Content Backend (REST /api/v1)   ← domain, planning, execution, persistence
        │
   Content Python SDK            ← official Python API client
    │        │        │
   CLI      MCP     Web apps     ← thin clients of the public contract

   Browser extension             ← JavaScript client of /api/v1

引擎会分析源事实，根据已安装的实现解析可行能力，构建确定性的执行计划，并将其作为可观测作业运行。数据库是事实来源；yt-dlp、ffmpeg、转录、大模型和 PDF 实现均位于专用边界之后。

领域模型将用户意图（GenerationRequest）、已解析的策略（ExecutionPlan）、执行过程（Job）和具体结果（Artifact）分别处理。完整设计请参阅架构概览、公开契约、领域模型和架构决策。

部署与安全

Content 面向部署在 amd64 或 arm64 上的单主机 Linux/macOS。Docker Compose 会同时运行 API 和内嵌工作进程，Web 应用则作为独立的 API 客户端运行。SQLite 和制品存储在本地持久化；无需 Redis、Celery、Kubernetes 或云基础设施。

带注释的 .env.example涵盖 UI 选择、镜像版本、端口、存储与交付、语言偏好、服务器端 Cookie 凭据、可选的大模型/STT 运行器、CORS 和通知。除非你进行配置，否则发布检查不会发出任何出站请求。

V1 API 没有内置身份验证：任何能够访问它的人都可以提交作业、上传文件并读取所有制品。请将其限制在可信网络中，或者在任何可从外部访问的实例前配置带身份验证的反向代理，并且不要公开该端口。攻击者访问 API 后能够和不能够执行的操作，已在 docs/operations/threat-model.md 中列明。有关配置、健康检查、数据布局、身份验证源和生产环境指南，请参阅部署；有关为何 V1 采用这一方案，请参阅 ADR 0024。

开发

该仓库是一个单体仓库，包含后端、Web 应用、CLI、MCP 服务、Chromium 扩展和 Python SDK。根目录下的 Makefile 是主要入口：

make install       # create the development environment and install packages
make validate      # formatting, linting, and hermetic tests: the official gate
make test-ui       # hermetic Streamlit application tests
make validate-all  # official gate plus UI and opt-in external-tool tests

主要测试套件无需联网。修改代码前，请阅读仓库架构和验证指南。发布请遵循发布操作手册。

文档

docs/README.md 是完整的文档索引。以下内容适合作为入门指南：

• 产品愿景
• 公开契约和领域模型
• 架构和不变量
• 存储与制品交付
• 部署与运维

许可证

Content 采用功能源代码许可证 1.1 版，未来转为 ALv2（FSL-1.1-ALv2），属于源代码可用。

简单来说：你可以阅读、审查、修改和运行 Content——无论是在家中供自己使用，还是在组织内部使用。唯一禁止的行为是将其或基于它构建的实质相似产品作为竞争性商业产品或服务提供。

每个版本在发布两年后都会转为 Apache 2.0。 该承诺写在许可证中，不可撤回。

版权所有 2026 Yann Orieult。“Content”和“Latent”是本项目及其作者作品的名称；分支项目不得将这些名称用于自己的产品。

版本 0.8.4 及之前的版本均以 AGPL-3.0-or-later 发布，并永久保留该许可证。 完整摘要请参阅 COMMERCIAL.md；目前没有单独的商业版本可供使用。

治理

内容由 Yann Orieult 以单人维护模式开发和维护。欢迎通过 issue 提交错误报告、想法和设计反馈。不接受代码贡献——未经邀请的拉取请求会直接关闭，不予审核；如需进行独立修改，请通过 fork 实现。请参阅 CONTRIBUTING.md 和 GOVERNANCE.md。

请按照 SECURITY.md 中的说明，私下报告安全问题。

© 2026 Yann Orieult。