# Tórculo in ten minutes

> A guide to writing and rendering your first pliego in ten minutes.

URL: https://torculo.joseluissaorin.com/en/ten-minutes · Reviewed: 2026-10-15 · Español: https://torculo.joseluissaorin.com/diez-minutos.md

By the end of this guide you will have a one-minute film with voice, music, ambience and
effects, written in a pliego that reads like the film. You need the reference implementation
(manim-saorín, with its `mesa` command), Tórculo's engine for `--motor gx`, and this
repository. The language's keywords are Spanish; the comments here explain them.

## Minute 1: the folder and its sound

```sh
mkdir -p ~/films/faro && cd ~/films/faro
python3 ~/Developer/torculo/conformance/tools/sonido.py --salida sonido
```

`sonido/banda/` has three cues (`1M1`, `1M2`, `cortinilla`) and `sonido/efectos/` three
ambiences (`amb sala bucle`, `amb lluvia bucle`, `amb taller bucle`) and four effects
(`pagina`, `campanilla`, `sello`, `tijera`), all synthesized and free (CC0). To use your own,
put other files in those folders.

## Minute 2: the servilleta

Write `faro.mesa` ("the lighthouse"), only prose and its soundtrack:

```text
MESA «El faro»
BANDA sonido/banda
EFECTOS sonido/efectos
MEZCLA para la web · sin stems
MÚSICA 1M2
AMBIENTE amb lluvia bucle

Cada noche, el farero subía los ciento doce escalones de la torre.
Nadie le había pedido que lo hiciera.
Aun así, encendía la luz.
```

```sh
mesa lee faro.mesa      # "LIMPIO": it is already a pliego
```

Every sentence is a clip; the engine chooses the shot and the piece. This can already be
rendered.

## Minutes 3 to 5: directing

Split the prose into a chapter and clips, each with a function and an affect, and put
things on the table:

```text
MESA «El faro»
formato 16:9 · sala crema · tirada borrador
BANDA sonido/banda
EFECTOS sonido/efectos
MEZCLA para la web · sin stems
REPARTO MARTA: ultramar, cita_f, seca, a la izquierda

== CAPÍTULO 1 · LA TORRE ============== tensión sube · tambor ultramar
MÚSICA 1M2
AMBIENTE amb lluvia bucle
ESPACIO patio

* apertura · sereno
di: Cada noche, el farero subía los ciento doce escalones de la torre.
pon: rescate «EL FARO»

* ilustración · nervioso
MARTA: —¿Por qué nunca se cansa?
pon: cartulina «ESCALÓN»
el escalón sube hasta el borde · despacio
al decir «cansa»: sonido: campanilla

* remate · solemne
di: Aun así, encendía la luz.
pon: sello «LUZ»
al decir «luz»: sonido: sello
> deja posar

== FIN ===
> silencio 2
```

`mesa lee` reports each error with the closest valid words. If you find yourself writing a
figure, look for the word instead: a manner (`despacio`, slowly), a distance (`lejos`, far),
a shot size (`primer`, close-up), an intensity (`tensa`, tense).

## Minutes 6 and 7: the voice

```sh
tools/pesado mesa graba faro.mesa        # local Supertonic; writes faro.tiempos.json
```

The sidecar keeps how long each beat lasts and when each word is said: `al decir` ("when
saying") anchors come from it. It is an input of the film like the pliego itself.

## Minute 8: look before rendering

```sh
tools/pesado mesa animatica faro.mesa --motor gx --sonido
```

One frame per beat with the real timing and sound. Check that each thing arrives when it is
said and that nothing covers anything else. Fix things here, not in the render.

## Minute 9: render

```sh
tools/pesado mesa toca faro.mesa --motor gx --sonido -o /tmp/faro.mp4
```

Beside the video you get the master (`/tmp/faro.master.wav`) and the soundtrack report
(`/tmp/faro.banda.json`): loudness should be around −14 LUFS and the cues those you asked
for.

## Minute 10: take it with you

```sh
mesa empaqueta faro.mesa                 # faro.mesapack: pliego, voice, sound and manifest
mesa desempaqueta faro.mesapack /another/folder
```

The package keeps relative paths and the hash of every file: on another machine the same
film comes out.

## Next

- The [cheat sheet](chuleta.en.md): the whole language on one page.
- The next layers: the scene (`EJE`, `LUZ`, film shots), movement and its manners, the look
  (`MATERIA`, `BOBINA`, `FORMATO`, transitions, the typographic river), the poster (`PALETA`,
  `LETRA`), the picture that listens (`INTENSIDAD`, `SOPORTE`) and the camera (`CÁMARA`,
  lenses, depth).
- The [specification](../spec/SPEC.md), when you want to know why.