Hoca

Hoca is Turkish for teacher (in English, "hodja"). Give Hoca a topic and it teaches it back as a short animated video in the style of 3Blue1Brown: black background, formulas that write themselves in, diagrams that draw and transform in step with a narrator.

npm run hoca -- "Türev nedir" --lang tr

If Hoca teaches you something, please give it a ⭐. It is the only thing this project asks for, and it helps other people find it.

Examples

Both videos below were made by Hoca from a single command. Claude Code wrote the script and the animation; the voice and every frame were produced on a laptop CPU (Apple M2 Pro), with no GPU and no speech API.

Press play for the full video with sound. The agent keeps its source notes next to each video in sources.md.

Quick start

You need Node 22+ and three tools: FFmpeg, librsvg and uv. Install them for your system:

macOS

brew install ffmpeg librsvg uv

Linux

# Debian, Ubuntu
sudo apt update && sudo apt install -y ffmpeg librsvg2-bin fontconfig curl git
# Arch
sudo pacman -S --needed ffmpeg librsvg fontconfig curl git
# Fedora: enable RPM Fusion first (https://rpmfusion.org/Configuration); the stock ffmpeg-free has no H.264 encoder
sudo dnf install -y librsvg2-tools fontconfig curl git && sudo dnf install -y ffmpeg --allowerasing

curl -LsSf https://astral.sh/uv/install.sh | sh    # uv, on any distribution

If your distribution ships a Node older than 22, install a current one with nvm (nvm install 22).

Windows

Hoca runs on Windows through WSL 2; it does not run in PowerShell or cmd directly, since the setup and the pipeline rely on a Unix shell. In an administrator PowerShell:

wsl --install

Restart, open the Ubuntu terminal it installed, and follow the Linux steps above inside it. Clone the repo into the Linux home folder (~/hoca, not /mnt/c/...), where rendering is much faster. explorer.exe outputs opens the finished videos in Windows.

Then, in this folder:

npm install             # 1. dependencies
cp .env.example .env    # 2. your settings: Hoca reads everything from this file
npm run setup           # 3. local voices (Turkish and English, about 400 MB, one time)
npm run doctor          # 4. checks that everything is ready
npm run hoca -- "Why is the sky blue?"     # 5. your first video

Hoca is configured through .env: who writes the video, its language, format, length, voice and subtitles all come from that file, and npm run config shows what is in effect. As copied, it gives you:

• Writer: Claude Code (AGENT=claude). If you use Codex instead, set AGENT=codex or add --agent codex. Neither needs an API key.
• Voice: EMA Lightning for Turkish and Kokoro for English, both local. Hoca picks by the video's language; TTS_PROVIDER overrides it.

The video lands in outputs/<topic>/<agent>/<topic>.mp4.

If you are a coding agent

Asked to install Hoca, or to make a video with it? Do this, in order:

1. Install what is missing. Check node --version (22 or newer), ffmpeg, rsvg-convert and uv, and install the absent ones with the command for this system from Quick start. On Windows, work inside WSL 2.
2. Set up the repo. Run npm install, then cp .env.example .env unless a .env is already there (never overwrite one), then npm run setup (it downloads about 400 MB of voices once, so let it finish), then npm run doctor. Fix every FAIL line before going on; a note line is informational.
3. Write the video yourself. Do not run npm run hoca -- "<topic>": that starts a second agent to do the writing. Read AGENTS.md and follow it. In short: if the hoca_* MCP tools are available, call hoca_brief, write the files it asks for, call hoca_check until the frames read clearly, then hoca_render. Otherwise use node bin/hoca.mjs brief "<topic>" --agent <you>, then check and render the same way.
4. Take settings from the user, not from guesses. Everything comes from .env. Pass a flag or tool argument (--format landscape, --lang tr, --no-voiceover) only when the user asked for it, and then on every command for that video. Do not edit .env.
5. Report the MP4 path, its duration and anything you could not verify. A plan, a script or still frames is not a finished video.

Make a video

npm run hoca -- "Türev nedir" --lang tr                  # Turkish, Turkish voice and subtitles
npm run hoca -- "How does HTTPS work?" --agent codex     # written by Codex
npm run hoca -- "Fourier series" --format landscape --duration 120    # a longer YouTube-style video
npm run hoca -- "What is entropy?" --no-voiceover        # silent, subtitles only

By default you get a vertical video of about 45 seconds (Reels, TikTok, Shorts) in English, with a voice-over and burned-in subtitles.

While it works, Hoca tells you what runs where and how far along it is:

Hoca: "Türev nedir"

Script     Claude Code CLI: remote model, on your Claude subscription or API login
Voice      EMA Lightning: local, on this machine's CPU, tr
Subtitles  tr, burned in + .srt file
Video      on this machine's CPU, 9 workers: vertical 1080x1920, about 45 s
Folder     outputs/turev/claude

Writing    done in 4:12  script and scenes pass the check
Voice      ████████████████████████ 100%  12/12 sentences
Frames     ██████████░░░░░░░░░░░░░░  42%  567/1350 frames  ETA 0:14

Writing the script takes a few minutes, since an AI agent researches the topic, writes the narration and codes the animation. Voice and rendering take well under a minute.

Settings

Every setting lives in .env, the copy of .env.example you made in Quick start (cp .env.example .env). Edit it to change the defaults for every video:

AGENT=claude            # who writes: claude | codex | ollama | openai | anthropic
LANGUAGE=en             # on-screen text, voice and subtitles: en, tr, ...
VIDEO_FORMAT=vertical   # vertical | landscape | square
VIDEO_DURATION=         # seconds; empty = 45 vertical, 120 landscape, 60 square
VOICEOVER=true
SUBTITLES=true
VIDEO_STYLE=3b1b        # add your own direction after it, e.g. "3b1b, warmer colors"

Or change one thing for one video with a flag: --agent, --lang, --format, --duration, --no-voiceover, --no-subtitles.

What runs where

If you choose a remote option instead (an API model, or an API voice), Hoca says so in the header before it starts.

If something goes wrong

• Run npm run doctor. It checks each tool, the voice and the agent, and says what to install.
• "already has a project": that topic was made before. Use npm run hoca -- render "<topic>" to render it again, or add --force to rewrite it.
• The video is too long or too short: the length is a target the script is written to. Hoca reports the real length; set --duration or edit the narration in video.json and render again.
• No voice for your language: only Turkish and English voices are installed by default. On macOS the system voice is used for other languages; see Voices under Advanced.

Advanced

Everything below is optional.

outputs/turev/claude/
  video.json         the script: narration per scene (and subtitle translations)
  scene-1.mjs ...    one animation per scene
  sources.md         what the agent verified
  turev.mp4, turev.tr.srt

npm run hoca -- check turev      # fast validation, writes preview/contact-sheet.png
npm run hoca -- render turev     # new MP4; unchanged sentences reuse their audio
npm run hoca -- render turev --format landscape    # same project, another format

npm run hoca -- "<topic>"            # write and render (same as: make "<topic>")
npm run hoca -- brief "<topic>"      # print the brief, for an agent you are chatting with
npm run hoca -- check <project>      # validate and write preview frames; no speech needed
npm run hoca -- render <project>     # MP4 + .srt
npm run hoca -- tts "<text>" -o clip.wav
npm run hoca -- config | doctor | list
npm run hoca -- mcp                  # MCP server over stdio, for Claude Code and Codex

claude mcp add --scope user hoca -- node /path/to/hoca/bin/hoca.mjs mcp
codex mcp add hoca -- node /path/to/hoca/bin/hoca.mjs mcp

npm run hoca -- "Bubble sort" --agent ollama --model qwen2.5-coder:32b

npm run hoca -- tts "Merhaba dünya" --lang tr --tts antalia -o test.wav

import { scene, numberPlane, tex, split, onBeat, duringBeat, lerp, linear } from '#kit';

const f = x => x * x;

export function render(ctx) {
  return scene(ctx, { title: 'How steep is a parabola?' }, rect => {
    const [graph, side] = split(rect, rect.vertical ? 'rows' : 'cols', [3, 2], rect.u * 4);
    const plane = numberPlane(graph, { x: [-3, 3], y: [-1, 5], numbers: true });
    const x = lerp(-1.5, 1.5, duringBeat(ctx, 1));
    return plane.svg(onBeat(ctx, 0)) + plane.plot(f, { draw: onBeat(ctx, 0, { delay: 0.6 }) })
      + (ctx.beat >= 1 ? plane.tangent(f, x) + plane.point(x, f(x)) : '')
      + tex(side.cx, side.cy, String.raw`\frac{d}{dx}\,x^2 = 2x`, { size: rect.u * 7, write: onBeat(ctx, 2, { length: 1.8, rate: linear }) });
  });
}

Credits and references

Inspiration. Hoca was inspired by a post by Andrej Karpathy.

Animation style. The look and the animation vocabulary come from manim, the open-source library Grant Sanderson built for 3Blue1Brown (MIT). Hoca ports its palette, rate functions and core animations to SVG. The 3Blue1Brown name, logo and pi characters are not part of that license and are not used.

Local voices. Speech is generated on your own CPU, which means no account, no per-character cost, nothing uploaded, and it works offline. The default models are tiny: on a laptop, the narration for a 45-second video is spoken in about five seconds.

Both Turkish model cards measure themselves on Freya-TR-Eval, the Turkish benchmark published by Freya Voice, and Patientdesk.ai keeps an independent re-run for every Turkish system. Those results are why EMA Lightning and Antalia-2 Mini are the Turkish defaults here.

Typesetting. Formulas are set with MathJax; text uses Latin Modern (GUST Font License).

Hoca itself is released under the MIT License. Third-party license texts are in NOTICE.md.

Support the project

Hoca is free and open source. If it was useful, star the repository, share a video you made with it, or open an issue with the topic it explained badly. Pull requests for new voices, languages and scene helpers are welcome.