# Tórculo

> Films written as pliegos: an open standard for video essays, explainers and animated shorts written in a text that reads like the film. (Películas escritas como pliegos: un estándar abierto para vídeo-ensayos, explicaciones y cortos animados escritos en un texto que se lee como la película.)

Tórculo is a standard by José Luis Saorín Ferrer (https://joseluissaorin.com). A film is a
**pliego**, a `.mesa` file in the language of Tórculo: a line-oriented script in **Spanish**
with **closed vocabularies**. The author says what happens and how ("la piedra rueda hasta
el borde · pesado"); the engine derives every number (places, curves, durations, colours,
loudness). The reference implementation is manim-saorín (command `mesa`), which renders on
Tórculo's engine, a fork of ManimGX. Every film carries its soundtrack: voice, music cues,
ambiences, a room and sound effects.

These are instructions for an AI agent asked to write a pliego (and, if needed, check and
render it). Follow them in order. The full specification is at the end of `llms-full.txt`.

## 1. The five rules that matter most

1. **No numbers.** Never write coordinates, durations, easing, colours in hex, font sizes or
   volumes. Say it in words; the engine computes the numbers. If you are about to write a
   number, there is a word for it (a manner, a distance, a shot size, an intensity).
2. **Closed vocabularies.** Every keyword comes from a fixed list (section 9). A word that is
   not in its list is an error, never a creative extension. Accents in keywords are optional
   (`ilustración` = `ilustracion`).
3. **Every film has a soundtrack**: `BANDA` (music folder), `EFECTOS` (effects folder),
   `MEZCLA`, and in each chapter or scene `MÚSICA`, `AMBIENTE`, `ESPACIO`, plus `sonido:`
   effects at the right moments.
4. **Texts that become pieces, and names that point to a text, go between Latin quotes
   «…»** (`pon: cartulina «CARTA»`, `marca: rodea «CARTA»`, `al decir «palabra»`), never
   straight quotes. Free text after `di:`, a speaker, `letrero (…):`, `terminal:` and the
   colophon goes without quotes. Free text can say anything; only keywords come from the
   lists. The field separator is the middle dot `·` (U+00B7) with spaces around it.
5. **Speakers must be declared** in `REPARTO` before they talk, and cannot be named with a
   reserved word (`nota`, `pie`, `el`, `la`, `di`, `ver`, `marca`…).

## 2. The smallest film: a servilleta

A pliego without chapters is prose: every sentence becomes a clip, and the engine decides
the shots and the pieces. Always start here.

```text
MESA «La servilleta»
BANDA sonido/banda
EFECTOS sonido/efectos
MEZCLA para la web · sin stems
MÚSICA 1M1
AMBIENTE amb sala bucle

Una mesa de trabajo, un pliego y una prensa.
Lo que se escribe en el pliego se estampa en la película.
Nada se dice en números: los números los pone el motor.
```

`BANDA` and `EFECTOS` are folders next to the pliego; names in the pliego are their file
names without extension. To get a ready set of free sounds (CC0), run
`python3 conformance/tools/sonido.py --salida ./sonido` from the Tórculo repository: it
writes `banda/1M1.wav`, `banda/1M2.wav`, `banda/cortinilla.wav` and in `efectos/`
`amb sala bucle`, `amb lluvia bucle`, `amb taller bucle`, `pagina`, `campanilla`, `sello`,
`tijera`. Only use names that exist in those folders.

## 3. A directed film

```text
MESA v2 «La prensa y el pliego»
formato 16:9 · sala crema · tirada borrador
BANDA sonido/banda
EFECTOS sonido/efectos
MEZCLA para la web · sin stems

ARCO pregunta→respuesta
MOTIVO «pliego» —empieza como papel en blanco y acaba siendo la película
REPARTO Gutenberg: ultramar

== CAPÍTULO 1 · EL TÓRCULO ============== tensión sube · tambor ultramar
MÚSICA 1M1
AMBIENTE amb taller bucle
ESPACIO estudio

* apertura · contenido
di: Un tórculo es una prensa de grabador.
pon: rescate «EL TÓRCULO»

* ilustración · nervioso
di: La plancha se trabaja una vez y se estampa tantas veces como haga falta.
al decir «estampa»: sonido: sello
ver: pila —una plancha | cien estampas

* prueba · seco
di: Cien estampas, y todas iguales.
terminal: estampas: 100 · diferencias: 0
marca: rodea «0»

== CAPÍTULO 2 · LA PLANCHA ============== tensión cae · tambor verde
MÚSICA 1M2
AMBIENTE amb sala bucle

* tesis · solemne
di: Lo que se escribe en el pliego no lleva números.
pon: cartulina «SIN NÚMEROS»

* remate · contenido
di: Los números los pone el motor.
al decir «motor»: sonido: campanilla
> deja posar

== FIN ====================
Estampado en Tórculo.
> silencio 2
```

- `== TITLE · tensión X · tambor Y ===` opens a chapter. `-- TITLE · hora --` opens a scene.
- `* FUNCTION · AFFECT` opens a clip (a beat). FUNCTION is one of the eleven functions and
  AFFECT one of the eight affects of section 9, **and nothing else** (`tensa` is an
  intensity, not an affect; `respuesta` is not a function). A bare `*` also works and lets
  the engine choose. Instead of a function you may write a shot: `* primer contrapicado de
  ella · seco`, where `ella` is a name from `REPARTO` or a piece.
- `di: TEXT` is the narration: its voice sets the beat's duration. A clip mixes freely
  narration, dialogue, pieces, movements, sounds and events.
- `NAME: —TEXT` is dialogue by a declared speaker (the dash is part of the speech, attached
  to its first word, as in Spanish dialogue).
- `al decir «word»: LINE` makes LINE happen when the voice says that word. Write the word as
  it is written in the `di:` text.
- `> EVENT` lines are events (section 9). `> dura N` gives a beat without voice its length;
  it is the one place where a number is allowed in a clip, together with `> silencio N`.
- `// comment` is ignored. Blank lines separate clips.

## 4. Putting things on the table

```text
pon: cartulina «VOX POPULI»          card; types: cartulina · dymo · rescate · sello · tira · texto · mano · apunte
letrero (cita): La frase citada      a sign; registers: cartulina · cita · cita máquina · cita moderna · mano · rescate
ver: votos —sí: 7 · no: 4            a visualization; the body after the dash is data (numbers allowed here)
terminal: mediana: 1207 libras       typewriter line
marca: subraya «1207»                gesture on a text: rodea · señala · subraya · tacha
arriba: Nature · 1907                caption above; also pie: and nota:
foto: galton                         a photograph of the project's archive
python: radio · grande               a drawing of the project's bestiary (only if it exists)
```

Placement is by relation, never by coordinates: `junto a «X»: …`, `bajo «X»: …`,
`delante de «X»: …`, `detrás de «X»: …`, `en las manos de ella: …`, `juntos: a · b · c
—en fila`. Body parts: el hombro · el pecho · el regazo · la cabeza · la espalda · las manos · los pies. Arrangements: amontonados · como flores · en abanico · en columna · en corro · en fila · en fila holgados · en rejilla.

## 5. Movement

A movement line is `[the] SUBJECT VERB [destination] · path · manner · grain`. It is
recognized by the verb. The curve, anticipation, overshoot and timing come from the engine
(Lasseter's principles).

```text
la piedra rueda hasta el borde · por el suelo · pesado · a treses
la carta salta hasta buzón · con anticipación
la hoja vuela fuera de campo por la derecha · ligero
la pluma flota hasta suelo · a la deriva · en dos
```

- Verbs: baja · cae · camina · corre · cruza · entra · esquiva · flota · gira · rebota · resbala · rueda · sale · salta · se apea · se encaja · se levanta · se sienta · sube · tiembla · tropieza · va · viaja · vuela.
- Verbs that act on another thing: agarra · alcanza · arrastra · cuelga · empuja · esquiva · huye · órbita · se apoya · sigue · suelta.
- Paths: a saltos · cayendo · en arco · en curva · en espiral · en zigzag · flotando · fuera de campo · girando · por el borde · por el camino · por el suelo · rebotando · recto · resbalando · rodando.
- Manners: a la deriva · a regañadientes · a tirones · con anticipación · con cuidado · de golpe · de un tirón · despacio · en volandas · ligero · pesado · resuelto · rozando · sin ganas · titubeante.
- Grains: a doses · a pulso · a treses · a unos; register: `en dos`.

After a `·` in a movement line only a path, manner, grain or `en dos` is valid: anything else
(`· deprisa`) is an error. The subject must be a piece placed before (`pon: cartulina
«PIEDRA»` creates `piedra`).

## 6. Sound design (always)

Preamble: `BANDA folder`, `EFECTOS folder`, `MEZCLA para la web | para cine · con stems |
sin stems`. In `REPARTO`, a voice and its side: `REPARTO ella: ultramar, cita_f, seca, a la
izquierda`. Voices: cita · cita_f · cita_f2 · cita_f3 · cita_m2 · narrador; colour: `seca` or `con radio`.

In a chapter or scene: `MÚSICA cue` (a file of `BANDA`; `MÚSICA ninguna` for none),
`AMBIENTE a · b` (layers of files of `EFECTOS`, looped), `ESPACIO room` (estadio · estudio · patio · radio · seco).

In a clip: `sonido: effect [a la izquierda | a la derecha | al centro]`, best anchored:
`al decir «golpe»: sonido: sello`. Sound events: `> entra la música «1M2»`,
`> la música se corta`, `> la música se apaga`, `> silencio de verdad`,
`> las voces se juntan en el centro`, `> cada voz a su lado`, `> la voz se vuelve radio`.

The engine mixes in four buses (voices, music, effects, ambiences), keeps a cue playing
while scenes repeat it, ducks music under the voice and masters to −14 LUFS for the web.

## 7. Cinema: scenes, axis, light, shots

```text
-- LA CARRETERA · diurna --
EJE de él a ella
LUZ de la izquierda · dura
MUNDO avanza · de frente
FONDO cielo · en el cielo
FONDO arboleda · cerca

* primer de él · contenido
él: —¿Falta mucho?
él mira a ella
```

- Shot sizes (ordered): general · conjunto · medio · americano · corto · primer · detalle. Heights: cenital · contrapicado · nadir · normal · picado. Fronts: escorzo · espalda · frontal · perfil · tres cuartos.
- Light directions: cenital · de atras · de frente · de la derecha · de la izquierda; hardness `dura` or `blanda`. Hours: amanece · atardece · diurna · mediodía · nocturna.
- Distances (ordered): al pie · al paso · cerca · a media distancia · lejos · al fondo · en el horizonte · en el cielo.
- Continuity warnings (not errors): jumping the axis, jumping two shot sizes, eyelines,
  directions, states. Silence them on purpose with `> cruza el eje` or `> salta`.

## 8. The look, posters, the picture that listens, the camera

```text
MATERIA papel khadi                      MATERIA risografía ultramar y rosa · desregistrada
BOBINA truca                             FORMATO 4:3
RÍO TIPOGRÁFICO · en fila                MONTAJE se acelera
PALETA verde, morado y amarillo          CARTEL columna a sangre a la izquierda · centro vacío
LETRA «PRENSA» · en Anton · a sangre · de amarillo
«PRENSA» se estampa
INTENSIDAD de templada a encendida       SOPORTE limpio
CÁMARA gran angular · con masa           HORIZONTE se inclina
lejos: pon: cartulina «MONTE»            el foco en MONTE
```

- Materials: acuarela · ninguna · papel · pincel · risografía · tejido · tinta; papers: cuaderno · escolar · grano fino · khadi · kraft · lienzo · satinado · tintado · torchón · verjurado · washi; film: noticiario · sin grano · truca; formats: `16:9`,
  `4:3`, `2,39:1`.
- Transitions are events (`> pasa página`), written as the first line of the clip they open:
  chasquido · corta · corta en la acción · cortinilla de tijera · desenfoque de pasada · encadena · entra de golpe · funde a blanco · funde a negro · funde desde blanco · funde desde negro · iris · la mano tapa · pasa página · se quema · sintoniza.
- Posters: `PALETA A, B y C` names exactly three colours with commas and `y` (field, figure,
  accent): amarillo · arena · azul · blanco · celeste · crema · lila · minio · morado · naranja · negro · rojo · rosa · tinta · ultramar · verde. `CARTEL` takes compositions separated by `·`:
  campo a sangre · campo en bandas · campo partido en diagonal · centro vacio · columna a sangre a la derecha · columna a sangre a la izquierda · diagonal de abajo a la izquierda arriba a la derecha · diagonal de arriba a la izquierda abajo a la derecha · disco detras · en silueta · enorme · figura delante de la letra · la letra corta a la figura · la letra delante de la figura · tercios.
- Signs are pieces, and **clip lines**: `LETRA «WORD» · en TYPEFACE · arrangement · place ·
  size · de COLOUR`. Typefaces: anton · la serifa de pretexto · league gothic · letra de mano · máquina de escribir · serifa. Arrangements: a sangre · en abanico · en columna · en escalera · girada · rota por el borde.
  Places: a la derecha · a la izquierda · abajo · arriba · en el centro. Sizes: `grande`, `enorme`, `gigante`. Then, in the same or a later
  clip: `«WORD» VERB` or `las letras de «WORD» VERB` with cae · caen · se abre · se abren · se apila · se apilan · se estampa · se estampan · se rompe · se rompen · se separa · se separan · se va · se van; `«WORD» es un
  ROLE` with barandilla · cielo · cuchilla · mascara · muro · persiana · porteria · suelo · ventana.
- Intensities (0 to 10): nula · quieta · serena · templada · viva · agitada · tensa · encendida · desatada · furiosa · rota; `INTENSIDAD de templada a encendida` is a ramp
  across the scene. Supports: limpio · usado · gastado · sucio · roto.
- Camera: `CÁMARA` takes a lens (gran angular · normal · ojo de pez · teleobjetivo), a weight (con masa · ligera · pesada), a hand
  (al hombro · en tripode) and a depth (poca profundidad · profundidad total), separated by `·`.
- Breaking a rule on purpose needs its reason: `> sin leer porque «…»`.

## 9. Closed vocabularies you will use most

- Affects: contenido · eufórico · exhausto · juguetón · nervioso · seco · sereno · solemne.
- Functions: apertura · cartel · contrapunto · digresión · eco · giro · ilustración · prueba · remate · respiro · tesis.
- Tensions: cae · mantiene · rompe · sube. Arcs: espiral · letania · pregunta→respuesta · ruina · tesis→antitesis→sintesis · viaje y vuelta.
- Drums (colours for a cast or chapter): ámbar · bermellón · naranja · rosa · ultramar · verde · violeta.
- Visualizations for `ver:`: alfiler · ancla · árbol · balanza · barras · brújula · bucle · cadena · caja · cancelación · ciclo · comparación · constelacion · convergencia · cuadrante · cuenta · curva · dado · diana · dispersión · distribución · dominó · ecuación · ejes · embudo · engranaje · escalera · espectro · espiral · flecha de proceso · fracción · globo · grieta · huella · interruptor · isla · jerarquía · laberinto · línea temporal · lista tachada · lupa · mapa · medidor · moneda · montón · multitud · onda · órbita · papeleta · péndulo · pila · ping pong · porcentaje · proceso · puente · recorrido · red · reloj · resta · semáforo · suma · telaraña · teorema · termómetro · títere · venn · versus · votos.
- Common events: `> dura N`, `> deja posar`, `> congela`, `> barre`, `> queda`, `> respira`,
  `> silencio N`, `> capítulo «…»`, `> temblor`, `> zoom de golpe`, `> la cámara vuelve`,
  `> se moja`, `> florece`, the transitions above and the sound events of section 6.

## 10. Details that matter (answers to what agents asked)

- **The format line**: `formato 16:9 · sala crema · tirada borrador`. `sala` is the paper
  (`crema`, the cream page; `pizarra`, a dark slate). `tirada` is the print run (`borrador`
  for drafts, `definitiva` for a final render with a fixed seed). Add `página desnuda` for a
  page without folio or stamp.
- **Voices**: the narration (`di:`) is spoken by `narrador` unless you write `di (VOICE):`;
  you do not declare the narrator. Voices: `narrador` (male, warm), `cita` (male),
  `cita_m2` (male, soft), `cita_f`, `cita_f2`, `cita_f3` (female). In `REPARTO NAME: drum,
  voice, colour, side`, only the drum is required.
- **Names**: any name declared in `REPARTO` (capitals or not, accents allowed) is valid
  unless it is a reserved word. The complete list of reserved words: a · al · alias · ancla · archivo · arco · arriba · bajo · bestiario · camino · canta · cascada · clip · con · contenido · de · del · delante · dentro · deriva · detras · di · eco · eje · el · en · escenario · fantasma · foco · fondo · formato · foto · fuera · hilo · junto · juntos · la · las · letra · letrero · los · luz · mano · marca · mesa · mientras · montaje · motivo · mundo · musica · nota · o · para · personaje · pica · pie · pon · por · prensada · python · que · recorte · relojes · reparto · revelado · se · sobre · sonido · su · sus · taller · terminal · un · una · ver · y.
  `él` and `ella` are valid names (with the accent); `el` and `la` are not. In `EJE de A a B`
  and `A mira a B`, A and B are names from `REPARTO`.
- **Drums** after `tambor` (chapter) or in `REPARTO` must be from the drum list:
  ámbar · bermellón · naranja · rosa · ultramar · verde · violeta (accents optional: `ámbar` = `ambar`). Accents are optional in every keyword:
  `de atrás` = `de atras`.
- **Pieces get their names from their text**: `pon: cartulina «HOGAZA»` creates the piece
  `hogaza` (lower case, accents kept); a movement line names it as `la hogaza`.
- **Movement without destination** happens in place (`la hogaza salta · de golpe`); with one,
  use `hasta`: `la carta salta hasta buzón`.
- **Order inside a clip** is the author's order, and it is respected. Write a transition as
  the first line after the clip header; anchor lines with `al decir «…»:` to place them in
  time. A clip may have only dialogue, only narration, or only pieces with `> dura N`.
- **A movement without destination** keeps its path and manner after `·`: `la entrada cae ·
  en espiral · ligero` is right.
- **A sign and its verb** may share a clip (`LETRA «FIN» · …` then `«FIN» se estampa`);
  `CARTEL` and `PALETA` written in a clip apply to that clip only.
- **Sound levels**: `MÚSICA`, `AMBIENTE` and `ESPACIO` can go in the preamble (the whole
  film), in a chapter or in a scene; the scene overrides the chapter, the chapter the
  preamble (a lower level replaces, it does not add). `MÚSICA ninguna` then `> entra la música «1M2»` is valid. `AMBIENTE` takes one
  or more layers separated by `·`. Rooms: `estadio` (a big echo), `patio` (an open
  courtyard), `estudio` (a dry studio), `radio` (a radio booth), `seco` (no room).
- **Hours** of a scene: `diurna`, `nocturna`, `amanece`, `atardece`, `mediodía`: they tint
  the light, nothing else.
- **The end**: `== FIN ==` is optional; the lines after it are a colophon shown at the end;
  `> silencio N` there is the final silence (without it the engine adds 3 seconds and warns).
  A `> silencio N` inside a clip is a pause in that beat.
- **Length**: the duration comes from the voice. About 150 spoken words make a minute.
- **Warnings are not errors**: `SALTO DE TALLA` (jumping from `general` to `primer`) or
  "más de 7 clips sin respiro" are advice. Put a `medio` between a `general` and a `primer`,
  or add `> salta` to say the jump is meant; add a clip with function `respiro` now and then.

- **Where each line goes.** Lines in capitals (`MATERIA`, `BOBINA`, `FORMATO`, `PALETA`,
  `CARTEL`, `INTENSIDAD`, `CÁMARA`, `HORIZONTE`, `MÚSICA`, `AMBIENTE`, `ESPACIO`, `EJE`, `LUZ`,
  `MUNDO`, `FONDO`) are **unit lines**: they go in the preamble, a chapter or a scene, and
  `PALETA` and `CARTEL` also inside a clip for that shot only. Everything else (`di:`,
  dialogue, `pon:`, `ver:`, `marca:`, `LETRA`, `«X» se estampa`, movements, `sonido:`,
  `> events`) is a **clip line** and goes after a `*` header. A clip line in the preamble is
  not shown.
- `MESA «Título»` and `MESA v2 «Título»` are both right; `v2` declares the language's epoch.
  The lower-case `formato` line is the preamble's properties; the capitalized `FORMATO` is a
  unit line that changes the aspect ratio of a scene.
- **Numbers are allowed** only in: aspect ratios (`16:9`), `> dura N`, `> silencio N`, the
  data of `ver:` and `terminal:`, the `#TALLER` and `#MANO` sections, and file names of
  sounds (`1M1`).
- **`ver:` data** is free text after the dash: `label: value · label: value`, or two sides
  with `|` (`ver: balanza —la voz del pueblo | los peritos`). The key before the dash must be
  from the `ver:` list.
- **`marca:`** acts on a text that is on screen in that clip (a `pon:`, `terminal:` or
  `letrero` line). **`al decir «word»`** matches a word of that clip's `di:` or dialogue,
  ignoring case and accents.
- **`REPARTO`** is only for characters who speak dialogue. Never declare the narrator.
- In this file `a | b` means "one of"; never write `|` in a pliego except inside `ver:` data.
- `tambor` (a risograph drum) is the accent colour of a chapter or a character; `tensión`
  says whether the chapter's energy rises (`sube`), holds (`mantiene`), falls (`cae`) or
  breaks (`rompe`); `ARCO` goes once in the preamble. The number of `=` after a chapter title
  is decoration.
- `pon: texto «…»` is plain text on the page; `pon: cartulina «…»` a coloured card; `rescate`
  a ransom-note cut-out; `dymo` an embossed label; `sello` a stamp; `apunte` a typed note.

## 11. Check, then voice, then look, then render

```sh
mesa lee pliego.mesa          # check: errors (E…) and warnings (W…); fix every error
mesa graba pliego.mesa        # synthesize the voice locally and write pliego.tiempos.json
mesa animatica pliego.mesa --motor gx --sonido      # one frame per beat with real timing
mesa toca pliego.mesa --motor gx --sonido -o film.mp4
mesa empaqueta pliego.mesa    # the portable project: pliego.mesapack
```

(`mesa` is `python -m manim_saorin.formato.cli` of manim-saorín.) `mesa lee` gives each
error with its line, why, the fix («¿quisiste decir…?») and an example; follow them. When in
doubt, ask instead of guessing: `mesa explica "palabra o línea"` (what it is, where it goes,
an example), `mesa chuleta` (the whole language on one page), `mesa bestiario pliego.mesa`
(the pieces the pliego can see and **the actions each one has**). `mesa nuevo "Título"`
starts a project with a commented template. Anything that looks like an instruction and is
not one is an error, never silent text on screen (E023), and so are an anchor word the
beat's voice never says (E025), an action the piece does not declare (E054) or a piece that
acts without a REPARTO name (E024). Common errors: a word outside its list
(E010 to E019), an ambiguous name (E020), a speaker named with a reserved word (E021), two
shouts in a clip (E030), a sound name not in `BANDA` or `EFECTOS` (E040 to E042). Look at
the animatic before rendering, and listen to the soundtrack report (`film.banda.json`):
loudness near −14 LUFS, the cues you asked for.

## 12. Pieces (when the table needs a drawing)

A bestiary (`PYTHON piezas.py` or `PIEZAS carpeta` in the preamble) adds named pieces,
placed with `python: nombre` and moved like any other. Each piece has a **card**. As JSON
(the portable form proposed in RFC 0005; a card is data, so numbers are fine there):

```json
{"nivel": "marioneta", "nombre": "tetera",
 "titulo": "La tetera",
 "descripcion": "Una tetera de hierro esmaltado con tapa, asa y pitorro, que silba al hervir.",
 "alto": 2.4, "mira": "izquierda",
 "partes": ["cuerpo", "tapa", "asa", "pitorro"],
 "esenciales": {"objeto": "pitorro"},
 "poses": ["reposo", "calienta", "silba"],
 "acciones": {"silba": ["calienta", "silba", "silba", "reposo"]},
 "ciclos": {"hierve": ["calienta", "reposo"]}}
```

- `nivel`: `dibujo` (one drawing), `partes` (named parts), `marioneta` (parts with pivots,
  poses, actions, cycles) or `personaje` (a puppet plus five views, expressions and mouths).
- `nombre`: ASCII without spaces; it is the seed and the word the pliego writes.
- `descripcion`: what is seen, for someone who cannot see it (20 characters or more).
- `alto`: natural height in scene units (the screen is 8 high). `mira`: `derecha`,
  `izquierda` or `frente`.
- `partes`: the piece's own names for its parts. `esenciales` maps each essential (`cara`,
  `boca`, `cabeza`, `mano`, `objeto`) to the part that is it; a cut by the frame's edge never
  removes an essential part. An object declares at least `objeto`.
- `poses`: names; `acciones`: action → list of poses; `ciclos`: cycle → list of poses that
  repeats. In the pliego, a declared character performs them: `TETERA silba` (the speaker or
  an `alias:` must name the piece).
- Check pieces with `mesa pieza comprueba piezas.py` (it draws each piece and tells what is
  missing).
- **Today a bestiary is code or a declarative file, not the JSON card**: a `.py` module whose
  functions draw the pieces (the card is a dict on each function, and pivots live in the
  drawing code), or `.personaje.toml` / `.marioneta.toml` files for characters and photo
  puppets. The JSON card above is the portable form being proposed; writing it is good
  practice, but `PIEZAS` loads `.py`, `.toml` or a folder of them.
- **Acting with a piece**: give it a name in the cast with an alias to the piece, then use
  that name: `REPARTO BUZÓN: verde, alias: buzon` and later `BUZÓN abre` (an action the
  card declares). A speaker that is also a puppet (`REPARTO CARTERO: ultramar, cita, alias:
  cartero`) can move like any piece: `CARTERO camina hasta buzon · despacio`.
- `python: nombre` places the piece where the composer decides; put a placement in front
  to choose (`junto a «CARTA»: python: buzon`).

## 13. Collage in motion and photo puppets

Photos, cut-outs, real video, type and pen in one shot, all in words (render with `--motor gx`):

```
MESA «La noche del estreno»
formato 16:9 · sala crema · silencio 3
PIEZAS piezas/
MARIONETA charlot · de la foto medios/chaplin.jpg · mira a la derecha
REPARTO CHARLOT: minio, cita_m2, alias: charlot
REPARTO TIJERAS: minio, alias: tijeras

* apertura · juguetón
a la izquierda: python: charlot · grande
CHARLOT: —Buenas noches, respetable público.
al decir «noches»: CHARLOT saluda

* prueba · nervioso
foto: medios/maquina.jpg · sin fondo · canto de tijera · sombra levantada · con cinta
di: La máquina ya tenía la crítica escrita.

* general · eufórico
clip de fondo: medios/baile.mp4 de 0:00 a 0:05
di: En la pantalla del fondo, el baile.

* giro · juguetón
clip: medios/baile.mp4 de 0:02 a 0:07 · sin fondo
delante: python: tijeras
di: Y la bailarina, recortada, sale de la pantalla y las tijeras cortan.
al decir «cortan»: TIJERAS corta
```

- `foto: x.jpg · sin fondo` cuts the figure out; then the edge (`canto de tijera | de
  troquel | rasgado | limpio`), shadow (`sombra pegada | levantada | sin sombra`) and
  fastening (`con cinta | con celo | con chincheta`). `recorte:` is already without background.
- `clip: x.mp4 de 0:02 a 0:07 · sin fondo` is a cut-out film, on twos (`en uno`, `en
  cuatro` to change). `clip de fondo:` fills the frame and leaves when its range ends.
- `MARIONETA name · de la foto x.jpg` makes a Terry Gilliam puppet from a photo (the jaw
  opens with the voice). Every photo puppet knows `saluda`, `celebra`, `señala`, `baila`,
  `se inclina`, `duda`, `grita`, `aplaude`, `en jarras`, and the cycles `anda`, `corre`;
  `.marioneta.toml` cards add their own. A half-length photo has no arms to wave.
- A piece that acts needs a REPARTO name whose alias is the piece, even if it never
  speaks (`REPARTO TIJERAS: minio, alias: tijeras`), and must be on the table already (in
  that beat, on an earlier line, or in an earlier beat). The colour of a REPARTO line is a
  drum (section 9) or an ink of the poster palette (`minio`, `tinta`, `azul`, `rojo`,
  `celeste`, `crema`…).
- A `clip de fondo` sits behind the pieces already on the table; the beat lasts at least
  its range (if the voice is shorter, the beat grows: warning W123). Several lines may share
  the same anchor (`al decir «cortan»: sonido: tijera` and `al decir «cortan»: TIJERAS
  corta`).
- `FONDO cielo · en el cielo` works without a bestiary: the house sets are `cielo`,
  `sierra`, `agua`, `arcada`, `celosia`, `ciudad`, `farola`, `lluvia`, `arboleda`, `cuarto`,
  `luna`.
- Placement prefixes: `a la izquierda:` · `a la derecha:` · `al fondo:` · `delante:` ·
  `lejos:` · `cerca:` · `en el cielo:` · `junto a «X»:` · `bajo «X»:`. No prefix means the
  composer chooses (there is no `en el centro:` prefix; `en el centro` is valid only
  inside a `LETRA` line).

## Optional

- [Everything in one file: this guide, the ten-minute guide, the cheat sheet and the specification in English and Spanish](https://torculo.joseluissaorin.com/llms-full.txt)
- [Specification (English, normative)](https://torculo.joseluissaorin.com/en/spec)
- [Especificación (traducción española)](https://torculo.joseluissaorin.com/especificacion)
- [Diez minutos con Tórculo](https://torculo.joseluissaorin.com/diez-minutos.md) · [Ten minutes with Tórculo](https://torculo.joseluissaorin.com/en/ten-minutes.md)
- [La chuleta](https://torculo.joseluissaorin.com/chuleta.md) · [The cheat sheet](https://torculo.joseluissaorin.com/en/cheat-sheet.md)
- [Conformance suite](https://torculo.joseluissaorin.com/conformidad)
- Repository: https://github.com/joseluissaorin/torculo (private for now)

## Esta web / This site

- [Tórculo, el estándar abierto de la mesa de trabajo](https://torculo.joseluissaorin.com/index.md): Tórculo es un estándar abierto en siete partes para escribir vídeos, dibujos y materias una vez y estamparlos muchas: la lengua de pliegos (.mesa), el proyecto portable, las piezas, el canon, las láminas, las materias y las tomas.
- [Radiointermisión: el corto y su pliego](https://torculo.joseluissaorin.com/radiointermision.md): Un corto animado que sale entero de un único pliego .mesa: el vídeo a un lado y el pliego al otro, sincronizados beat a beat.
- [Obras hechas con Tórculo](https://torculo.joseluissaorin.com/obras.md): Lo que el motor sabe hacer de verdad: Radiointermisión, las hojas del bestiario, las materias y el collage.
- [Especificación de Tórculo](https://torculo.joseluissaorin.com/especificacion.md): El texto normativo del estándar Tórculo: la lengua de pliegos, el proyecto portable, las piezas, el canon, las láminas, las materias y las tomas. Manda el inglés si discrepan.
- [Referencia de la lengua de pliegos](https://torculo.joseluissaorin.com/lengua.md): Los vocabularios cerrados de la lengua de Tórculo (época 2), generados desde el parser de la implementación de referencia, con su perfil y su fuente; los códigos de diagnóstico y la gramática EBNF.
- [Casos: los pliegos de la conformidad](https://torculo.joseluissaorin.com/galeria.md): Diez pliegos de la batería de conformidad, uno por perfil y por rasgo de la lengua, cada uno con su vídeo, su banda sonora sintetizada y su hoja de contactos.
- [Tomas en el navegador](https://torculo.joseluissaorin.com/tomas.md): Una toma es el trabajo del motor grabado una vez; el elemento <manimgx-film> la estampa en la página con el propio motor de ManimGX compilado a WebAssembly y WebGPU, sin Python.
- [Láminas: dibujos que se revelan](https://torculo.joseluissaorin.com/laminas.md): Una lámina es un dibujo a mano listo para que cualquier motor lo haga aparecer a pluma sin volver a calcular la mano: la imagen se rasteriza una vez y un atlas de tiempo dice cuándo llega la pluma a cada píxel.
- [Conformidad](https://torculo.joseluissaorin.com/conformidad.md): La batería de conformidad de Tórculo: los casos que una implementación debe pasar para llamarse conforme, y el último informe.
- [Gobernanza y comunidad](https://torculo.joseluissaorin.com/gobernanza.md): Cómo se decide en Tórculo, cómo se propone un cambio (RFC), cómo se contribuye y cómo se avisa de un fallo de seguridad.
- [Chuleta de la lengua de pliegos](https://torculo.joseluissaorin.com/chuleta.md): La lengua de Tórculo en una página: cabeceras, prefijos, eventos y las órdenes para rodar.
- [Tórculo en diez minutos](https://torculo.joseluissaorin.com/diez-minutos.md): Una guía para escribir y rodar el primer pliego en diez minutos.
- [Para agentes](https://torculo.joseluissaorin.com/agentes.md): Qué puede leer un agente en esta web y en qué formato: llms.txt, llms-full.txt, el gemelo .md de cada hoja, los vocabularios en JSON y los pliegos en texto.
- [Tórculo, the open standard of the worktable](https://torculo.joseluissaorin.com/en/index.md): Tórculo is an open standard in seven parts for writing videos, drawings and materials once and printing them many times: the pliego language (.mesa), the portable project, pieces, canon, plates, materials and takes.
- [Radiointermisión: the film and its pliego](https://torculo.joseluissaorin.com/en/radiointermision.md): An animated short that comes entirely from a single .mesa pliego: the video on one side and the pliego on the other, in sync beat by beat.
- [Works made with Tórculo](https://torculo.joseluissaorin.com/en/works.md): What the engine really does: Radiointermisión, the bestiary sheets, the materials and the collage.
- [Tórculo specification](https://torculo.joseluissaorin.com/en/spec.md): The normative text of the Tórculo standard: the pliego language, the portable project, pieces, canon, plates, materials and takes.
- [Pliego language reference](https://torculo.joseluissaorin.com/en/language.md): The closed vocabularies of the Tórculo language (epoch 2), generated from the reference implementation’s parser, with their profile and source; diagnostic codes and the EBNF grammar.
- [Cases: the conformance pliegos](https://torculo.joseluissaorin.com/en/gallery.md): Ten pliegos from the conformance suite, one per profile and language feature, each with its video, its synthesised soundtrack and its contact sheet.
- [Takes in the browser](https://torculo.joseluissaorin.com/en/takes.md): A take is the engine’s work recorded once; the <manimgx-film> element prints it on the page with ManimGX’s own engine compiled to WebAssembly and WebGPU, with no Python.
- [Plates: drawings that reveal themselves](https://torculo.joseluissaorin.com/en/plates.md): A plate is a hand drawing ready for any engine to make it appear in pen without recomputing the hand: the image is rasterised once and a time atlas says when the pen reaches each pixel.
- [Conformance](https://torculo.joseluissaorin.com/en/conformance.md): The Tórculo conformance suite: the cases an implementation must pass to call itself conforming, and the latest report.
- [Governance and community](https://torculo.joseluissaorin.com/en/governance.md): How decisions are made in Tórculo, how to propose a change (RFC), how to contribute and how to report a security flaw.
- [Pliego language cheat sheet](https://torculo.joseluissaorin.com/en/cheat-sheet.md): The Tórculo language on one page: headers, prefixes, events and the commands to render.
- [Tórculo in ten minutes](https://torculo.joseluissaorin.com/en/ten-minutes.md): A guide to writing and rendering your first pliego in ten minutes.
- [For agents](https://torculo.joseluissaorin.com/en/agents.md): What an agent can read on this site and in which format: llms.txt, llms-full.txt, each page’s .md twin, the vocabularies as JSON and the pliegos as text.

## Galería / Gallery

- [«La servilleta»](https://torculo.joseluissaorin.com/galeria/servilleta.md): El pliego más pequeño: unas frases y la banda. Sin cabeceras, sin clips; todo lo demás lo decide el motor.
- [«La prensa y el pliego»](https://torculo.joseluissaorin.com/galeria/dirigido.md): Un capítulo dirigido: función y afecto en cada clip, piezas del taller, una marca y la banda anclada a la voz.
- [«El puerto»](https://torculo.joseluissaorin.com/galeria/escena.md): Una escena de cine: eje, luz, mundo que avanza, diálogo con hablante declarado y voces a cada lado.
- [«El oficio»](https://torculo.joseluissaorin.com/galeria/oficio.md): Los principios de Lasseter como comportamiento por defecto: el pliego solo dice maneras, y cada gesto lleva su efecto.
- [«El taller y la mano»](https://torculo.joseluissaorin.com/galeria/taller.md): Las secciones #TALLER y #MANO: calibrar el oficio con palabras sin tocar la gramática.
- [«El aspecto»](https://torculo.joseluissaorin.com/galeria/aspecto.md): Materia del plano, bobina, formato, transiciones, río tipográfico y montaje. Todo en palabras.
- [«Cada plano es un cartel»](https://torculo.joseluissaorin.com/galeria/cartel.md): Perfil cartel: cada plano compuesto como un cartel; los signos son piezas y el texto se teje.
- [«La cámara como objeto»](https://torculo.joseluissaorin.com/galeria/camara.md): Perfil cámara: lente, masa, profundidad y tiempo por capas.
- [«La imagen que oye»](https://torculo.joseluissaorin.com/galeria/oido.md): Perfil oído: la imagen sigue al sonido real; la intensidad gobierna temblor, desregistro y grano.
- [«La banda»](https://torculo.joseluissaorin.com/galeria/banda.md): Perfil sonido: cues que siguen entre escenas, ambientes por capas, la sala de los efectos y el máster medido.

## Datos / Data

- [vocabularios.json](https://torculo.joseluissaorin.com/spec/vocabularios.json): los vocabularios cerrados, generados desde el parser / closed vocabularies, generated from the parser
- [diagnosticos.json](https://torculo.joseluissaorin.com/spec/diagnosticos.json): códigos de diagnóstico / diagnostic codes
- [llms-full.txt](https://torculo.joseluissaorin.com/llms-full.txt): todo el texto / all the text