content

<!-- markdownlint-disable MD013 MD026 MD033 MD036 MD041 -->
<div align="center">

# Content

## Turn URLs, files, and text into media, knowledge, and documents.

**One self-hosted engine. HomeTube for YouTube, Content Studio for everything else — plus a browser extension, an MCP server, a CLI, a typed SDK, and the REST API underneath them all.**

[![Latest release](https://img.shields.io/github/v/release/LatentNoise/content?sort=semver&display_name=tag)](https://github.com/LatentNoise/content/releases/latest)
[![CI](https://github.com/LatentNoise/content/actions/workflows/ci.yml/badge.svg)](https://github.com/LatentNoise/content/actions/workflows/ci.yml)
[![Docker](https://img.shields.io/badge/Docker-amd64%20%C2%B7%20arm64-2496ED.svg?logo=docker&logoColor=white)](docs/operations/deployment.md)
[![License](https://img.shields.io/badge/License-AGPL--3.0--or--later-green.svg)](LICENSE)

[Quick start](#quick-start) ·
[HomeTube](#hometube--youtube-focused) ·
[Coming from HomeTube?](#coming-from-standalone-hometube) ·
[All the clients](#the-clients) ·
[Connect an agent](#mcp-server--for-agents-and-ides) ·
[Read the docs](docs/README.md)

</div>

Content is a self-hosted engine that turns supported sources into media,
transcripts, summaries, translations, images, metadata, Markdown, PDF, and
more. The **backend** analyzes each source, determines what it can actually
produce, plans and runs the job, records its history, and delivers the results.

Everything else is a **client of one public contract**: **HomeTube** for the
focused YouTube experience, **Content Studio** for general workflows, a
**Chromium extension** for the tab you are already on, the **`content-mcp`**
server for agents, a **CLI** for terminals and cron, a **typed Python SDK** for
applications, the **REST API** for every other language, and **Content
Console** to watch the engine work. Pick one or several — none of them is a
layer the others have to pass through, and none of them holds business logic of
its own.

**HomeTube** is the quickest way to see what that means: paste a YouTube URL,
pick what you want out of it, and watch the files land in your library.

<div align="center">
  <img src="https://github.com/LatentNoise/content/releases/download/v0.1.0/2026-08-09-hometube-demo.gif"
       alt="HomeTube demo — paste a YouTube URL, choose the outputs, watch the job deliver into the library"
       width="80%">
  <br>
  <sub><b>HomeTube in Content</b> — paste a YouTube URL, choose what you want,
  follow the job into your library. <a href="#hometube--youtube-focused">More about HomeTube ↓</a></sub>
</div>

<!-- Visuals are produced in media/ (untracked) and attached to releases —
see media/README.md. -->

> [!NOTE]
> **A proven workflow, now growing into a platform.** The standalone
> [HomeTube](https://github.com/EgalitarianMonkey/hometube) container has passed
> **300,000 package downloads on GitHub Container Registry**. It keeps running
> and stays maintained — nothing breaks, and there is no deadline. Content is
> where that work continues, and where its users are invited to move at their
> own pace.
>
> The two are separate projects: standalone HomeTube has not been retrofitted to
> run on Content. The **HomeTube app in this repository is a new UI on the
> Content engine**, carrying the same workflow forward.
> [Coming from standalone HomeTube? ↓](#coming-from-standalone-hometube)

## Quick start

Docker Compose is the only runtime prerequisite. Install from the published
images — nothing to clone or build:

```bash
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
```

The default `.env` starts the complete local stack:

| Service | Default URL | Purpose |
| --- | --- | --- |
| **Content Studio** | <http://localhost:8502> | General requests across URL, file, upload, and inline-text sources |
| **HomeTube** | <http://localhost:8501> | Focused YouTube video and playlist workflow |
| **Content Console** | <http://localhost:8503> | Health, configuration, storage, jobs, events, and logs |
| **Content API** | <http://localhost:8010/docs> | REST API, OpenAPI, and embedded worker |

Open **Content Studio** for the general workflow, or **HomeTube** if your
source is YouTube. You can also skip both web apps entirely and drive the same
engine from the [MCP server, CLI, SDK, extension, or REST API](#the-clients).

Everything stays in the installation folder: `./data` holds the database, jobs,
and artifacts; finished files are delivered to `./playground/output`. Set
`CONTENT_DELIVERY_DIR_HOST` in `.env` to point at your own NAS or media library
instead — its sub-folders then become the destination choices offered in the
clients.

Update later with:

```bash
docker compose pull && docker compose up -d
```

<details>
<summary><b>Build from source instead</b> — for development or to include the
optional speech-to-text runner</summary>

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

The repository's `docker-compose.yml` adds local `build:` definitions beside
the same images. [`deploy/docker-compose.yml`](deploy/docker-compose.yml) is
the build-free deployment file used above; a test keeps the two aligned.

</details>

## One source, many artifacts

The same engine serves media and document workflows:

```text
                             ┌─ 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
```

Each branch starts with a declarative request. You describe the results;
Content resolves what is possible, plans the work, runs the available tools,
and records where every artifact came from. No yt-dlp flags, ffmpeg pipelines,
transcription glue, or LLM orchestration in the client.

## The clients

One engine, one contract, several independent front doors. Every client below
speaks the same `GenerationRequest`, sees the same resolved capabilities, and
produces the same artifacts — they differ in ergonomics, not in what they can
ask for. HomeTube is entirely optional; so is every other row.

| Client | Best for | Start here |
| --- | --- | --- |
| **[HomeTube](#hometube--youtube-focused)** | The simplest YouTube video or playlist → library experience | Included in Docker Compose at `:8501` |
| **[Content Studio](#content-studio--the-whole-contract-in-a-form)** | General capability-driven requests from URLs, uploads, server files, and inline text | Included in Docker Compose at `:8502` |
| **[Chromium extension](#chromium-extension--the-tab-you-are-already-on)** | Sending the current Chrome, Brave, Edge, or Vivaldi tab to Content | Download the release zip, unzip, *Load unpacked* |
| **[MCP server](#mcp-server--for-agents-and-ides)** | Giving Claude, an IDE, or another MCP agent real artifacts instead of talk | `uv tool install content-mcp` |
| **[CLI](#cli--terminals-scripts-and-cron)** | Terminals, scripts, cron jobs, and raw request files | `uv tool install content-cli` |
| **[Python SDK](#python-sdk--typed-sync-and-async)** | Typed sync and async application integration | `pip install content-sdk` |
| **[REST API](#rest-api--every-other-language)** | Any language or integration that speaks HTTP | `/api/v1`, Swagger at `:8010/docs` |
| **[Content Console](#content-console--observe-and-pilot-the-engine)** | Observing and operating the engine | Included in Docker Compose at `:8503` |

### HomeTube — YouTube, focused

<http://localhost:8501> · [README](apps/web-hometube/README.md)

Paste a URL, choose the media and related artifacts, and follow the job into
your library — the workflow demonstrated at the top of this page.

With HomeTube in Content, you can:

- download a video or playlist as video or audio, with quality, codec,
  container, audio-language, and subtitle choices;
- remove or mark sponsored segments with SponsorBlock, cut clips, use
  server-side cookie credentials, and embed subtitles, chapters, thumbnails,
  and metadata;
- give every artifact a readable name and deliver it into a filesystem library
  watched by Plex, Jellyfin, or Emby;
- ask the same source for a transcript, summary, thumbnail, or metadata — not
  just the downloaded media — when the required runners are available.

HomeTube is deliberately focused: it does not accept file, upload, or
inline-text sources, and it does not expose the broader document workflow or
PDF output. For those, use Content Studio, the API, CLI, or SDK. **HomeTube is
a Content client, not a layer every Content user must pass through.**

**It has no settings of its own.** It reads the engine's configuration, so what
changes HomeTube lives in the `.env` beside your `docker-compose.yml`: the
delivery library whose sub-folders become the destination choices
(`CONTENT_DELIVERY_DIR_HOST`), the languages pre-selected for audio and
subtitles (`CONTENT_LANGUAGE_PRIMARY`, `CONTENT_LANGUAGES_SECONDARIES`,
`CONTENT_VO_FIRST`, `CONTENT_LANGUAGE_PRIMARY_INCLUDED_IN_SUBTITLES`), and the
server-side cookie file that unlocks age-restricted or members-only videos
(`CONTENT_CREDENTIALS` — HomeTube only ever shows its id; the file never leaves
the server). Nothing is ever pre-selected that the source does not offer, and
no default is final.

[HomeTube's README](apps/web-hometube/README.md#configu