dsh-reelsmaker

Readme

# dsh-reelsmaker

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that
turns lines of narration into a finished vertical reel — spoken, captioned,
1080×1920, ready to upload.

**No API key. No account. No ffmpeg.**

```
you:  make a reel about why my tool needs no API key
dsh:  [make_reel] Rendering a 5-beat reel…
      Rendered 16.4s reel (5 beats): out/why-my-tool-needs-no-api-key.mp4
```

---

## Install

```sh
dsh plugin add dsh-reelsmaker
```

Or straight from source, which skips the registry entirely:

```sh
dsh plugin add github:aayan-cloud/dsh-reelsmaker
```

Either works: `dsh plugin add` forwards to pnpm, and there is no build step, since
the plugin is plain ESM and Remotion compiles the JSX at render time.

Or try it without the harness at all:

```sh
git clone https://github.com/aayan-cloud/dsh-reelsmaker
cd dsh-reelsmaker && npm install
node lib/make-reel.js "Every reel here is just a text file." "No editor, and nothing dragged onto a timeline." "Free, and open source."
```

---

## Why this exists

Every voice plugin in the harness ecosystem today either wants an API key or
falls back to browser speech, and the video plugins render one fixed style.

This uses **Microsoft Edge's neural TTS** — the engine behind Edge's Read Aloud —
which is free and needs no account, and renders with
[Remotion](https://remotion.dev), so the whole chain runs on hardware you already
own.

**The agent writes the words. This makes the video.** The tool takes finished
narration lines rather than a topic on purpose: the harness already has a model
that writes better copy than any template would, so generating the script
internally would replace a good writer with a worse one.

---

## The tool

`make_reel` — each line becomes one beat, spoken and shown on screen.

| parameter | | |
| --- | --- | --- |
| `lines` | required | 4–6 narration lines, under ~12 words each |
| `title` | | output filename, defaults to the first line |
| `outDir` | | where the MP4 lands |
| `voice` | | Edge voice id, e.g. `en-US-AriaNeural` |
| `rate` | | speaking rate, e.g. `+12%` |

Returns `{ path, seconds, beats }`.

---

## Two decisions worth knowing about

**Beat lengths are measured, never estimated.** A beat has to be exactly as long
as the line spoken over it. Guessing from character count is close, and close
compounds — across six beats the captions end up a third of a second off the
voice, which reads as broken rather than as a small error. So the pipeline speaks
first, counts the MPEG frames in each MP3 to get an exact duration, and only then
times the beats. There is no ffmpeg anywhere; the frame headers are parsed
directly.

**Captions are burned in, not optional.** Short-form is watched muted by default,
so a reel whose story lives only in the voice track is a reel most viewers never
receive. Every line is spoken *and* shown. The audio is an upgrade for people who
turn it on, never a dependency.

---

## Loading it from source on Windows

The harness tutorial says a local plugin path "must be absolute". That is true
on Unix and not sufficient on Windows: a bare `C:/...` path reaches Node's ESM
loader as protocol `c:` and throws `ERR_UNSUPPORTED_ESM_URL_SCHEME` before the
plugin loads. Use a `file://` URL:

```yaml
- insert:
    - id: reelsmaker
      name: 'file:///C:/path/to/dsh-reelsmaker/index.js'
```

```sh
dsh web --patch ./dev-patch.yml
```

Set `REELSMAKER_PROBE=1` to print a line when the plugin registers, which is how
you tell "loaded and registered" apart from "the config composed but nothing ran".

## Known limits

- **The render is foreground.** It takes 30s–3min depending on length, and the
  call blocks for that time. Moving it to `ctx.jobs.start()` as a background job
  is the obvious upgrade; it is not done yet.
- **One visual style.** Narrated statements on a drifting gradient. It suits
  explainer and announcement reels; it is not a product-video tool. For cinematic
  product work see [video-shotcraft](https://github.com/Vincentwei1021/video-shotcraft).
- **DeepSeek Harness is in developer preview** and promises
  compatibility-breaking changes, so this will need maintenance.

---

## Licence

MIT for the code here. **Remotion is not MIT** — it is free for individuals and
companies of up to three people, and larger companies need a paid company
licence. See <https://remotion.dev/license>.