Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs(website): the Custom effects page

EtienneLescota666011756f1
diff --git a/website/docs/ai-editing.md b/website/docs/ai-editing.md
index e5188ac3d..587191f21 100644
--- a/website/docs/ai-editing.md
+++ b/website/docs/ai-editing.md
@@ -41,7 +41,7 @@ The ChatGPT and GitHub Copilot sign-in options were **removed in 1.8.0**. They w
## Using the agent
-Describe the edit in plain language — "cut the dead air in the intro", "zoom in when I open the terminal". The agent works through real, undoable timeline operations, not a re-render: it can add and adjust trims, zooms, speed regions, annotations (text, arrows, and blurs that hide private details on screen), imported audio tracks with their fades, and Full Camera segments, add automatic zooms on your clicks, edit a clip's in/out points and crop, place another source's footage, duplicate, reorder or remove clips, and read the transcript to find what you're referring to. It also sets the look of the video: background, padding, rounded corners, shadow, device frame, format, the camera layout, the cursor and the master volume. It can also turn the [captions](./captions.md) on, style and place them, and translate them into another language itself.
+Describe the edit in plain language — "cut the dead air in the intro", "zoom in when I open the terminal". The agent works through real, undoable timeline operations, not a re-render: it can add and adjust trims, zooms, speed regions, annotations (text, arrows, and blurs that hide private details on screen), imported audio tracks with their fades, and Full Camera segments, add automatic zooms on your clicks, edit a clip's in/out points and crop, place another source's footage, duplicate, reorder or remove clips, and read the transcript to find what you're referring to. It also sets the look of the video: background, padding, rounded corners, shadow, device frame, format, the camera layout, the cursor and the master volume. It can also turn the [captions](./captions.md) on, style and place them, and translate them into another language itself. And it can write a visual effect the settings don't offer: see [Custom effects](./effects.md).
The panel around it:
diff --git a/website/docs/editing-timeline.md b/website/docs/editing-timeline.md
index 8bb042ac7..a1eabdd0f 100644
--- a/website/docs/editing-timeline.md
+++ b/website/docs/editing-timeline.md
@@ -78,6 +78,10 @@ A row of preset buttons (0.5×, 1×, 1.5×, 2×, 4×) and a free numeric field f
A span where the webcam fills the frame instead of sitting in its layout box — useful for a talking-head intro in the middle of a screen recording. Only meaningful when the recording has a webcam track.
+### Effect regions
+
+A visual effect an AI agent wrote for the project. Its row shows under the Full Camera segments once the project has one: see [Custom effects](./effects.md#in-the-editor).
+
### Annotations
Four types, picked from the **Type** row in the inspector. Switching type keeps the region's span and its place in the picture.
diff --git a/website/docs/effects.md b/website/docs/effects.md
new file mode 100644
index 000000000..206a60f1a
--- /dev/null
+++ b/website/docs/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: Custom effects
+description: "Ask an AI agent for a visual effect the settings don't offer. It writes a GPU shader that OpenScreen draws in the preview and in every export."
+keywords:
+ - custom video effects
+ - shader effects
+ - WGSL
+ - AI video effects
+ - GPU effects
+---
+
+# Custom effects
+
+When the settings don't have the look you want, ask an agent for it: a ripple from each click, a vignette that breathes, a fade to black over the last seconds. The agent writes the effect as a small GPU shader, and OpenScreen draws it in the preview and in every export, MP4 and GIF, on Windows, macOS and Linux.
+
+Effects come from an agent: the built-in chat or an MCP client such as Claude Code or Codex (see [AI editing](./ai-editing.md)). Once an effect is in the project, you adjust it yourself in the editor.
+
+## Asking for an effect
+
+Describe what you want to see, and when: "a ripple on every click", "fade to black over the last two seconds, captions included". The agent writes the effect, places it on the timeline, and can look at the result with `getFrames` without exporting the video.
+
+An effect knows where the cursor is and where each click landed, where the recording and the webcam sit in the video after zooms and layout, and the time. So a halo can follow the mouse, and a ripple can start from each click, wherever the zoom has moved it.
+
+## In the editor
+
+Effects get their own row on the timeline, under the Full Camera segments, once the project has one. Each block carries the effect's name. Move it, resize it, copy and paste it or delete it like any other region, and `Ctrl/Cmd + Z` undoes the change. One effect plays at a time: a paste onto another effect is refused.
+
+Click a block to open its inspector:
+
+- **A control for each setting** the agent gave the effect: a slider, a switch, a color or a point.
+- **Applies to**, where the effect is drawn:
+ - **Image**, the default: the recording, the webcam, the cursor and the background, under your annotations and captions, which stay legible.
+ - **Text**: the annotations and captions only.
+ - **Both**: the whole frame, text included, for a fade to black that also covers the captions.
+- **Cost**: **Light**, **Medium**, **Heavy** or **Very heavy** (see [below](#cost)).
+- **Code**: the shader, read-only, with **Copy code**. To change it, ask the agent.
+
+A copied effect pasted into another project brings its code along.
+
+## Cost
+
+The cost is estimated from the code, by counting how many times the effect reads the picture for each pixel. The same code gets the same tier on every computer. Nothing is refused for its cost: the heavier the effect, the shorter the stretch it suits.
+
+| Tier | Typical effects | Suits |
+|---|---|---|
+| **Light** | vignette, color grade, click ripple | the whole video |
+| **Medium** | chromatic aberration, small blur, glitch | a few tens of seconds |
+| **Heavy** | strong blur, bokeh | a transition, a highlight |
+| **Very heavy** | raymarching, simulations | a few seconds: the export stays exact but slower, and the preview can slow down on a small GPU |
+
+## If an effect doesn't compile
+
+An agent's code is compiled before the effect is accepted. Code that fails is refused with the compiler's error, and the project doesn't change.
+
+A project opened on another computer can still meet a compiler that disagrees. The effect is then not drawn, its inspector shows **Doesn't compile on this computer** with the error, and the export goes on without it.
+
+## Projects from someone else
+
+A project carries the code of its effects, so opening someone else's project runs code you didn't write. That code runs only on the GPU, with no access to your files, the network or the app's memory.
+
+## For agent authors
+
+The tools are `addEffect`, `setEffect`, `setEffectDefinition` and `getEffect`, and `removeModifier` takes an effect off. The full contract, the `effect(uv)` function, what it can read and its rules, is the MCP resource `openscreen://effects/contract`.
diff --git a/website/i18n/TRANSLATING.md b/website/i18n/TRANSLATING.md
index 1920df10d..a0f714330 100644
--- a/website/i18n/TRANSLATING.md
+++ b/website/i18n/TRANSLATING.md
@@ -21,13 +21,13 @@ Replace `<locale>` with `fr`, `es`, `pt-BR`, `ja`, `zh-CN`, `zh-TW` or `de`.
3. **`i18n/<locale>/docusaurus-plugin-content-docs/current.json`**: sidebar category and link labels. `version.label` is not shown.
4. **`i18n/<locale>/docusaurus-plugin-content-docs/current/`**: one translated copy of each doc, same file name and folder:
- `intro.md`, `installation.md`, `quick-start.md`, `faq.md`
- - `recording.md`, `media-library.md`, `editing-timeline.md`, `captions.md`, `ai-editing.md`, `export.md`, `cli.md`
+ - `recording.md`, `media-library.md`, `editing-timeline.md`, `captions.md`, `ai-editing.md`, `effects.md`, `export.md`, `cli.md`
- `guides/product-demo-video.md`
Start from a copy of `website/docs/<file>`. In the front matter, translate `title`, `description`, `sidebar_label` and `keywords`. Leave `id`, `slug` and `sidebar_position` as they are.
5. **`i18n/<locale>/docusaurus-plugin-content-pages/`**: one translated copy of each `website/src/pages/**/*.mdx`, same path (`alternatives/screen-studio.mdx`, `screen-recorder-linux.mdx`…). Translate `title`, `description` and `keywords` in the front matter. Prices, plan limits and "checked September 2026" dates are facts: copy them as they are, in your language's number and currency format. Keep the Sources list's URLs, and translate the trademark note.
-**All 12 docs of a locale land together.** The docs link to each other with relative paths (`./captions.md`), and Docusaurus only resolves those between files in the same folder: with some docs translated and others not, the build fails on broken links. A doc missing from a finished locale would also be published under `/<locale>/docs/` in English, marked as your language.
+**All 13 docs of a locale land together.** The docs link to each other with relative paths (`./captions.md`), and Docusaurus only resolves those between files in the same folder: with some docs translated and others not, the build fails on broken links. A doc missing from a finished locale would also be published under `/<locale>/docs/` in English, marked as your language.
## Keep every heading's English anchor
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md
index 39c593670..e1f6e6be5 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ Die Anmeldeoptionen für ChatGPT und GitHub Copilot wurden **in 1.8.0 entfernt**
## Den Agenten nutzen {#using-the-agent}
-Beschreibe die Änderung in Alltagssprache, etwa „schneide die Stille im Intro heraus“ oder „zoome hinein, wenn ich das Terminal öffne“. Der Agent arbeitet mit echten, rückgängig machbaren Operationen auf der Zeitleiste, nicht mit einem neuen Rendering: Er kann Schnitte, Zooms, Geschwindigkeitsbereiche, Annotationen (Text, Pfeile und Unschärfen, die private Details auf dem Bildschirm verbergen), importierte Audiospuren samt Ein- und Ausblendung und Full-Camera-Segmente hinzufügen und anpassen, automatische Zooms auf deine Klicks setzen, Start- und Endpunkte und den Zuschnitt eines Clips ändern, Material einer anderen Quelle platzieren, Clips duplizieren, umsortieren oder entfernen und das Transkript lesen, um herauszufinden, was du meinst. Außerdem stellt er das Aussehen des Videos ein: Hintergrund, Innenabstand, abgerundete Ecken, Schatten, Geräterahmen, Format, das Kamera-Layout, den Cursor und die Gesamtlautstärke. Er kann außerdem die [Untertitel](./captions.md) einschalten, gestalten und platzieren und sie selbst in eine andere Sprache übersetzen.
+Beschreibe die Änderung in Alltagssprache, etwa „schneide die Stille im Intro heraus“ oder „zoome hinein, wenn ich das Terminal öffne“. Der Agent arbeitet mit echten, rückgängig machbaren Operationen auf der Zeitleiste, nicht mit einem neuen Rendering: Er kann Schnitte, Zooms, Geschwindigkeitsbereiche, Annotationen (Text, Pfeile und Unschärfen, die private Details auf dem Bildschirm verbergen), importierte Audiospuren samt Ein- und Ausblendung und Full-Camera-Segmente hinzufügen und anpassen, automatische Zooms auf deine Klicks setzen, Start- und Endpunkte und den Zuschnitt eines Clips ändern, Material einer anderen Quelle platzieren, Clips duplizieren, umsortieren oder entfernen und das Transkript lesen, um herauszufinden, was du meinst. Außerdem stellt er das Aussehen des Videos ein: Hintergrund, Innenabstand, abgerundete Ecken, Schatten, Geräterahmen, Format, das Kamera-Layout, den Cursor und die Gesamtlautstärke. Er kann außerdem die [Untertitel](./captions.md) einschalten, gestalten und platzieren und sie selbst in eine andere Sprache übersetzen. Und er kann einen visuellen Effekt schreiben, den die Einstellungen nicht bieten: siehe [Eigene Effekte](./effects.md).
Der Bereich drumherum:
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/de/docusaurus-plugin-content-docs/current/editing-timeline.md
index 6c6fefdf3..a4428c338 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ Eine Reihe von Vorgabe-Schaltflächen (0.5×, 1×, 1.5×, 2×, 4×) und ein frei
Ein Abschnitt, in dem die Webcam das Bild füllt, statt in ihrem Layout-Rahmen zu sitzen. Praktisch für ein Intro mit dir vor der Kamera mitten in einer Bildschirmaufnahme. Nur sinnvoll, wenn die Aufnahme eine Webcam-Spur hat.
+### Effektbereiche {#effect-regions}
+
+Ein visueller Effekt, den ein KI-Agent für das Projekt geschrieben hat. Seine Reihe erscheint unter den Full-Camera-Segmenten, sobald das Projekt einen enthält: siehe [Eigene Effekte](./effects.md#in-the-editor).
+
### Annotationen {#annotations}
Vier Arten, wählbar in der Zeile **Type** im Inspektor. Beim Umschalten bleiben die Zeitspanne des Bereichs und seine Stelle im Bild erhalten.
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/de/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..c16fa7f4e
--- /dev/null
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: Eigene Effekte
+description: "Bitte einen KI-Agenten um einen visuellen Effekt, den die Einstellungen nicht bieten. Er schreibt einen GPU-Shader, den OpenScreen in der Vorschau und in jedem Export zeichnet."
+keywords:
+ - eigene Videoeffekte
+ - Shader-Effekte
+ - WGSL
+ - KI-Videoeffekte
+ - GPU-Effekte
+---
+
+# Eigene Effekte
+
+Wenn die Einstellungen den Look nicht haben, den du suchst, bitte einen Agenten darum: eine Welle bei jedem Klick, eine Vignette, die atmet, eine Abblende ins Schwarze in den letzten Sekunden. Der Agent schreibt den Effekt als kleinen GPU-Shader, und OpenScreen zeichnet ihn in der Vorschau und in jedem Export, MP4 wie GIF, unter Windows, macOS und Linux.
+
+Effekte kommen von einem Agenten: dem eingebauten Chat oder einem MCP-Client wie Claude Code oder Codex (siehe [KI-Bearbeitung](./ai-editing.md)). Sobald ein Effekt im Projekt ist, stellst du ihn selbst im Editor ein.
+
+## Einen Effekt anfragen {#asking-for-an-effect}
+
+Beschreibe, was du sehen willst, und wann: „eine Welle bei jedem Klick“, „Abblende ins Schwarze über die letzten zwei Sekunden, Untertitel inklusive“. Der Agent schreibt den Effekt, legt ihn auf die Zeitleiste und kann sich das Ergebnis mit `getFrames` ansehen, ohne das Video zu exportieren.
+
+Ein Effekt weiß, wo der Cursor ist und wo jeder Klick gelandet ist, wo die Aufnahme und die Webcam nach Zooms und Layout im Video sitzen, und welcher Zeitpunkt gerade ist. So kann ein Lichthof der Maus folgen, und eine Welle kann von jedem Klick ausgehen, wohin der Zoom ihn auch verschoben hat.
+
+## Im Editor {#in-the-editor}
+
+Effekte bekommen eine eigene Reihe auf der Zeitleiste, unter den Full-Camera-Segmenten, sobald das Projekt einen enthält. Jeder Block trägt den Namen des Effekts. Verschiebe ihn, ändere seine Größe, kopiere und füge ihn ein oder lösche ihn wie jeden anderen Bereich, und `Ctrl/Cmd + Z` macht die Änderung rückgängig. Es läuft immer nur ein Effekt: Einfügen auf einen anderen Effekt wird abgelehnt.
+
+Klicke auf einen Block, um seinen Inspektor zu öffnen:
+
+- **Ein Regler für jede Einstellung**, die der Agent dem Effekt gegeben hat: ein Schieberegler, ein Schalter, eine Farbe oder ein Punkt.
+- **Gilt für**, also wo der Effekt gezeichnet wird:
+ - **Bild**, die Voreinstellung: die Aufnahme, die Webcam, der Cursor und der Hintergrund, unter deinen Annotationen und Untertiteln, die lesbar bleiben.
+ - **Texte**: nur die Annotationen und Untertitel.
+ - **Beides**: das ganze Bild, Text inklusive, für eine Abblende ins Schwarze, die auch die Untertitel bedeckt.
+- **Kosten**: **Leicht**, **Mittel**, **Schwer** oder **Sehr schwer** (siehe [unten](#cost)).
+- **Code**: der Shader, schreibgeschützt, mit **Code kopieren**. Um ihn zu ändern, bitte den Agenten darum.
+
+Ein kopierter Effekt, der in ein anderes Projekt eingefügt wird, bringt seinen Code mit.
+
+## Kosten {#cost}
+
+Die Kosten werden aus dem Code geschätzt: Gezählt wird, wie oft der Effekt das Bild pro Pixel liest. Derselbe Code bekommt auf jedem Computer dieselbe Stufe. Nichts wird wegen seiner Kosten abgelehnt: Je schwerer der Effekt, desto kürzer der Abschnitt, der zu ihm passt.
+
+| Stufe | Typische Effekte | Passt für |
+|---|---|---|
+| **Leicht** | Vignette, Farbkorrektur, Welle beim Klick | das ganze Video |
+| **Mittel** | chromatische Aberration, leichte Unschärfe, Glitch | einige Dutzend Sekunden |
+| **Schwer** | starke Unschärfe, Bokeh | einen Übergang, einen Höhepunkt |
+| **Sehr schwer** | Raymarching, Simulationen | wenige Sekunden: Der Export bleibt exakt, aber langsamer, und die Vorschau kann auf einer kleinen GPU langsamer werden |
+
+## Wenn ein Effekt nicht kompiliert {#if-an-effect-doesnt-compile}
+
+Der Code eines Agenten wird kompiliert, bevor der Effekt angenommen wird. Code, der scheitert, wird mit dem Fehler des Compilers abgelehnt, und das Projekt ändert sich nicht.
+
+Ein Projekt, das auf einem anderen Computer geöffnet wird, kann trotzdem auf einen Compiler treffen, der anderer Meinung ist. Der Effekt wird dann nicht gezeichnet, sein Inspektor zeigt **Lässt sich auf diesem Computer nicht kompilieren** mit dem Fehler, und der Export läuft ohne ihn weiter.
+
+## Projekte von anderen {#projects-from-someone-else}
+
+Ein Projekt trägt den Code seiner Effekte: Öffnest du das Projekt eines anderen, führst du also Code aus, den du nicht geschrieben hast. Dieser Code läuft nur auf der GPU, ohne Zugriff auf deine Dateien, das Netzwerk oder den Speicher der App.
+
+## Für Agent-Entwickler {#for-agent-authors}
+
+Die Werkzeuge sind `addEffect`, `setEffect`, `setEffectDefinition` und `getEffect`, und `removeModifier` entfernt einen Effekt. Der vollständige Vertrag, also die Funktion `effect(uv)`, was sie lesen kann und ihre Regeln, ist die MCP-Ressource `openscreen://effects/contract`.
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md
index aa9d101cf..991cc24e1 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ Las opciones de inicio de sesión con ChatGPT y GitHub Copilot se **eliminaron e
## Usar el agente {#using-the-agent}
-Describe la edición con tus propias palabras: "corta el tiempo muerto de la introducción", "haz zoom cuando abro la terminal". El agente trabaja con operaciones reales de la línea de tiempo, que se pueden deshacer, y no con un nuevo renderizado: puede agregar y ajustar recortes, zooms, regiones de velocidad, anotaciones (texto, flechas y desenfoques que ocultan datos privados en pantalla), pistas de audio importadas con sus fundidos y segmentos de cámara a pantalla completa, agregar zooms automáticos en tus clics, editar los puntos de entrada y salida y el recorte de un clip, colocar el material de otra fuente, duplicar, reordenar o quitar clips, y leer la transcripción para encontrar aquello a lo que te refieres. También ajusta el aspecto del vídeo: fondo, margen, esquinas redondeadas, sombra, marco de dispositivo, formato, la disposición de la cámara, el cursor y el volumen general. También puede activar los [subtítulos](./captions.md), darles estilo y colocarlos, y traducirlos él mismo a otro idioma.
+Describe la edición con tus propias palabras: "corta el tiempo muerto de la introducción", "haz zoom cuando abro la terminal". El agente trabaja con operaciones reales de la línea de tiempo, que se pueden deshacer, y no con un nuevo renderizado: puede agregar y ajustar recortes, zooms, regiones de velocidad, anotaciones (texto, flechas y desenfoques que ocultan datos privados en pantalla), pistas de audio importadas con sus fundidos y segmentos de cámara a pantalla completa, agregar zooms automáticos en tus clics, editar los puntos de entrada y salida y el recorte de un clip, colocar el material de otra fuente, duplicar, reordenar o quitar clips, y leer la transcripción para encontrar aquello a lo que te refieres. También ajusta el aspecto del vídeo: fondo, margen, esquinas redondeadas, sombra, marco de dispositivo, formato, la disposición de la cámara, el cursor y el volumen general. También puede activar los [subtítulos](./captions.md), darles estilo y colocarlos, y traducirlos él mismo a otro idioma. Y puede escribir un efecto visual que los ajustes no ofrecen: consulta [Efectos personalizados](./effects.md).
El panel que lo rodea:
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/es/docusaurus-plugin-content-docs/current/editing-timeline.md
index d065f84dc..86cd7e6fe 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ Una fila de botones predefinidos (0.5×, 1×, 1.5×, 2×, 4×) y un campo numér
Un tramo en el que la cámara web llena el cuadro en lugar de ocupar su recuadro de la disposición: útil para una introducción hablando a cámara en medio de una grabación de pantalla. Solo tiene sentido cuando la grabación tiene una pista de cámara web.
+### Regiones de efecto {#effect-regions}
+
+Un efecto visual que un agente de IA escribió para el proyecto. Su fila aparece bajo los tramos de cámara a pantalla completa en cuanto el proyecto tiene uno: consulta [Efectos personalizados](./effects.md#in-the-editor).
+
### Anotaciones {#annotations}
Cuatro tipos, que se eligen en la fila **Tipo** del inspector. Cambiar de tipo conserva el tramo de la región y su lugar en la imagen.
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/es/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..02936bb40
--- /dev/null
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: Efectos personalizados
+description: "Pide a un agente de IA un efecto visual que los ajustes no ofrecen. Escribe un shader de GPU que OpenScreen dibuja en la vista previa y en cada exportación."
+keywords:
+ - efectos de vídeo personalizados
+ - efectos shader
+ - WGSL
+ - efectos de vídeo con IA
+ - efectos GPU
+---
+
+# Efectos personalizados
+
+Cuando los ajustes no tienen el aspecto que buscas, pídeselo a un agente: una onda en cada clic, una viñeta que respira, un fundido a negro en los últimos segundos. El agente escribe el efecto como un pequeño shader de GPU, y OpenScreen lo dibuja en la vista previa y en cada exportación, MP4 y GIF, en Windows, macOS y Linux.
+
+Los efectos vienen de un agente: el chat integrado o un cliente MCP como Claude Code o Codex (consulta [Edición con IA](./ai-editing.md)). Una vez que el efecto está en el proyecto, lo ajustas tú mismo en el editor.
+
+## Pedir un efecto {#asking-for-an-effect}
+
+Describe lo que quieres ver, y cuándo: «una onda en cada clic», «fundido a negro en los dos últimos segundos, subtítulos incluidos». El agente escribe el efecto, lo coloca en la línea de tiempo y puede ver el resultado con `getFrames` sin exportar el vídeo.
+
+Un efecto sabe dónde está el cursor y dónde cayó cada clic, dónde están la grabación y la cámara web en el vídeo tras los zooms y la disposición, y en qué momento está. Así, un halo puede seguir al ratón, y una onda puede salir de cada clic, allí donde el zoom lo haya llevado.
+
+## En el editor {#in-the-editor}
+
+Los efectos tienen su propia fila en la línea de tiempo, bajo los tramos de cámara a pantalla completa, en cuanto el proyecto tiene uno. Cada bloque lleva el nombre del efecto. Muévelo, cambia su tamaño, cópialo y pégalo o elimínalo como cualquier otra región, y `Ctrl/Cmd + Z` deshace el cambio. Solo se reproduce un efecto a la vez: pegar sobre otro efecto se rechaza.
+
+Haz clic en un bloque para abrir su inspector:
+
+- **Un control para cada ajuste** que el agente dio al efecto: un deslizador, un interruptor, un color o un punto.
+- **Se aplica a**, dónde se dibuja el efecto:
+ - **Imagen**, por defecto: la grabación, la cámara web, el cursor y el fondo, bajo tus anotaciones y subtítulos, que siguen legibles.
+ - **Textos**: solo las anotaciones y los subtítulos.
+ - **Ambos**: el cuadro entero, texto incluido, para un fundido a negro que también cubra los subtítulos.
+- **Coste**: **Ligero**, **Medio**, **Pesado** o **Muy pesado** (consulta [más abajo](#cost)).
+- **Código**: el shader, de solo lectura, con **Copiar código**. Para cambiarlo, pídeselo al agente.
+
+Un efecto copiado y pegado en otro proyecto se lleva su código.
+
+## Coste {#cost}
+
+El coste se estima a partir del código, contando cuántas veces lee el efecto la imagen por cada píxel. El mismo código recibe el mismo nivel en todos los ordenadores. Nada se rechaza por su coste: cuanto más pesado es el efecto, más corto es el tramo que le conviene.
+
+| Nivel | Efectos típicos | Conviene para |
+|---|---|---|
+| **Ligero** | viñeta, etalonaje, onda al hacer clic | todo el vídeo |
+| **Medio** | aberración cromática, desenfoque pequeño, glitch | unas decenas de segundos |
+| **Pesado** | desenfoque fuerte, bokeh | una transición, un momento destacado |
+| **Muy pesado** | raymarching, simulaciones | unos segundos: la exportación sigue siendo exacta pero más lenta, y la vista previa puede ralentizarse en una GPU pequeña |
+
+## Si un efecto no compila {#if-an-effect-doesnt-compile}
+
+El código de un agente se compila antes de aceptar el efecto. El código que falla se rechaza con el error del compilador, y el proyecto no cambia.
+
+Un proyecto abierto en otro ordenador aún puede toparse con un compilador que no está de acuerdo. El efecto entonces no se dibuja, su inspector muestra **No compila en este ordenador** con el error, y la exportación continúa sin él.
+
+## Proyectos de otras personas {#projects-from-someone-else}
+
+Un proyecto lleva el código de sus efectos, así que abrir el proyecto de otra persona ejecuta código que no escribiste tú. Ese código solo se ejecuta en la GPU, sin acceso a tus archivos, a la red ni a la memoria de la app.
+
+## Para autores de agentes {#for-agent-authors}
+
+Las herramientas son `addEffect`, `setEffect`, `setEffectDefinition` y `getEffect`, y `removeModifier` quita un efecto. El contrato completo, es decir, la función `effect(uv)`, lo que puede leer y sus reglas, es el recurso MCP `openscreen://effects/contract`.
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md
index 22f5e25c3..e3fc85198 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ Les options de connexion ChatGPT et GitHub Copilot ont été **supprimées dans
## Utiliser l'agent {#using-the-agent}
-Décrivez la modification en langage courant : « coupe les temps morts de l'intro », « zoome quand j'ouvre le terminal ». L'agent travaille avec de vraies opérations de timeline annulables, pas avec un nouveau rendu : il peut ajouter et ajuster des coupes, des zooms, des régions de vitesse, des annotations (texte, flèches et flous qui masquent une information privée à l'écran), des pistes audio importées avec leurs fondus, et des segments Caméra plein écran, ajouter des zooms automatiques sur vos clics, modifier les points d'entrée et de sortie et le recadrage d'un clip, placer les images d'une autre source, dupliquer, réordonner ou retirer des clips, et lire la transcription pour trouver ce dont vous parlez. Il règle aussi l'apparence de la vidéo : fond, marge, coins arrondis, ombre, cadre d'appareil, format, disposition de la caméra, curseur et volume général. Il peut aussi activer les [sous-titres](./captions.md), les styliser et les placer, et les traduire lui-même dans une autre langue.
+Décrivez la modification en langage courant : « coupe les temps morts de l'intro », « zoome quand j'ouvre le terminal ». L'agent travaille avec de vraies opérations de timeline annulables, pas avec un nouveau rendu : il peut ajouter et ajuster des coupes, des zooms, des régions de vitesse, des annotations (texte, flèches et flous qui masquent une information privée à l'écran), des pistes audio importées avec leurs fondus, et des segments Caméra plein écran, ajouter des zooms automatiques sur vos clics, modifier les points d'entrée et de sortie et le recadrage d'un clip, placer les images d'une autre source, dupliquer, réordonner ou retirer des clips, et lire la transcription pour trouver ce dont vous parlez. Il règle aussi l'apparence de la vidéo : fond, marge, coins arrondis, ombre, cadre d'appareil, format, disposition de la caméra, curseur et volume général. Il peut aussi activer les [sous-titres](./captions.md), les styliser et les placer, et les traduire lui-même dans une autre langue. Et il peut écrire un effet visuel que les réglages n'offrent pas : voir [Effets personnalisés](./effects.md).
Le panneau qui l'entoure :
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/editing-timeline.md
index 8b95ebdf0..5105538ab 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ Une rangée de boutons de préréglage (0.5×, 1×, 1.5×, 2×, 4×) et un champ
Un passage où la webcam remplit le cadre au lieu de rester dans l'emplacement que lui donne sa disposition : utile pour une introduction face caméra au milieu d'un enregistrement d'écran. N'a de sens que si l'enregistrement contient une piste webcam.
+### Régions d'effet {#effect-regions}
+
+Un effet visuel qu'un agent IA a écrit pour le projet. Sa rangée apparaît sous les passages Caméra plein écran dès que le projet en contient un : voir [Effets personnalisés](./effects.md#in-the-editor).
+
### Annotations {#annotations}
Quatre types, à choisir dans la rangée **Type** de l'inspecteur. Changer de type conserve la plage de la région et sa place à l'image.
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..8d3d6b67e
--- /dev/null
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: Effets personnalisés
+description: "Demandez à un agent IA un effet visuel que les réglages n'offrent pas. Il écrit un shader GPU qu'OpenScreen dessine dans l'aperçu et dans chaque export."
+keywords:
+ - effets vidéo personnalisés
+ - effets shader
+ - WGSL
+ - effets vidéo IA
+ - effets GPU
+---
+
+# Effets personnalisés
+
+Quand les réglages n'ont pas le rendu que vous cherchez, demandez-le à un agent : une onde à chaque clic, un vignettage qui respire, un fondu au noir sur les dernières secondes. L'agent écrit l'effet sous la forme d'un petit shader GPU, et OpenScreen le dessine dans l'aperçu et dans chaque export, MP4 comme GIF, sous Windows, macOS et Linux.
+
+Les effets viennent d'un agent : le chat intégré, ou un client MCP comme Claude Code ou Codex (voir [Montage par IA](./ai-editing.md)). Une fois l'effet dans le projet, vous le réglez vous-même dans l'éditeur.
+
+## Demander un effet {#asking-for-an-effect}
+
+Décrivez ce que vous voulez voir, et à quel moment : « une onde à chaque clic », « un fondu au noir sur les deux dernières secondes, sous-titres compris ». L'agent écrit l'effet, le place sur la timeline, et peut regarder le résultat avec `getFrames` sans exporter la vidéo.
+
+Un effet sait où est le curseur et où chaque clic a eu lieu, où se trouvent l'enregistrement et la webcam dans la vidéo après les zooms et la disposition, et quel est le moment. Un halo peut donc suivre la souris, et une onde partir de chaque clic, où que le zoom l'ait déplacé.
+
+## Dans l'éditeur {#in-the-editor}
+
+Les effets ont leur propre rangée dans la timeline, sous les passages Caméra plein écran, dès que le projet en contient un. Chaque bloc porte le nom de l'effet. Déplacez-le, redimensionnez-le, copiez-collez-le ou supprimez-le comme n'importe quelle autre région, et `Ctrl/Cmd + Z` annule la modification. Un seul effet joue à la fois : un collage sur un autre effet est refusé.
+
+Cliquez sur un bloc pour ouvrir son inspecteur :
+
+- **Un contrôle pour chaque réglage** que l'agent a donné à l'effet : un curseur, un interrupteur, une couleur ou un point.
+- **S'applique à**, là où l'effet est dessiné :
+ - **Image**, par défaut : l'enregistrement, la webcam, le curseur et le fond, sous vos annotations et vos sous-titres, qui restent lisibles.
+ - **Textes** : les annotations et les sous-titres seulement.
+ - **Les deux** : l'image entière, textes compris, pour un fondu au noir qui couvre aussi les sous-titres.
+- **Coût** : **Léger**, **Moyen**, **Lourd** ou **Très lourd** (voir [plus bas](#cost)).
+- **Code** : le shader, en lecture seule, avec **Copier le code**. Pour le modifier, demandez-le à l'agent.
+
+Un effet copié puis collé dans un autre projet emporte son code avec lui.
+
+## Coût {#cost}
+
+Le coût est estimé à partir du code, en comptant combien de fois l'effet lit l'image pour chaque pixel. Le même code reçoit le même palier sur tous les ordinateurs. Rien n'est refusé pour son coût : plus l'effet est lourd, plus le passage qui lui convient est court.
+
+| Palier | Effets typiques | Convient à |
+|---|---|---|
+| **Léger** | vignettage, étalonnage, onde au clic | toute la vidéo |
+| **Moyen** | aberration chromatique, petit flou, glitch | quelques dizaines de secondes |
+| **Lourd** | gros flou, bokeh | une transition, un temps fort |
+| **Très lourd** | raymarching, simulations | quelques secondes : l'export reste exact mais plus lent, et l'aperçu peut ralentir sur un petit GPU |
+
+## Si un effet ne compile pas {#if-an-effect-doesnt-compile}
+
+Le code d'un agent est compilé avant que l'effet soit accepté. Un code qui échoue est refusé avec l'erreur du compilateur, et le projet ne change pas.
+
+Un projet ouvert sur un autre ordinateur peut quand même tomber sur un compilateur qui n'est pas d'accord. L'effet n'est alors pas dessiné, son inspecteur affiche **Ne compile pas sur cet ordinateur** avec l'erreur, et l'export se poursuit sans lui.
+
+## Les projets des autres {#projects-from-someone-else}
+
+Un projet emporte le code de ses effets : ouvrir le projet de quelqu'un d'autre exécute donc du code que vous n'avez pas écrit. Ce code ne tourne que sur le GPU, sans accès à vos fichiers, au réseau ni à la mémoire de l'app.
+
+## Pour les auteurs d'agents {#for-agent-authors}
+
+Les outils sont `addEffect`, `setEffect`, `setEffectDefinition` et `getEffect`, et `removeModifier` retire un effet. Le contrat complet, c'est-à-dire la fonction `effect(uv)`, ce qu'elle peut lire et ses règles, est la ressource MCP `openscreen://effects/contract`.
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md
index 833fdbd9a..6ec2fc3af 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ ChatGPT と GitHub Copilot のサインインは、**1.8.0 で削除されまし
## エージェントを使う {#using-the-agent}
-行いたい編集を、普段の言葉で伝えます(「イントロの無音部分をカットして」「ターミナルを開いたところでズームして」など)。エージェントは再レンダリングではなく、元に戻せる実際のタイムライン操作で作業します。トリム、ズーム、再生速度の範囲、注釈(テキスト、矢印、画面上の個人情報を隠すぼかし)、取り込んだオーディオトラックとそのフェード、フルスクリーンカメラのセグメントの追加と調整、クリック位置への自動ズームの追加、クリップのイン点とアウト点やクロップの編集、別のソースの映像の配置、クリップの複製・並べ替え・削除ができ、文字起こしを読んで、あなたが指している箇所を見つけます。背景、余白、角の丸み、影、デバイスフレーム、フォーマット、カメラのレイアウト、カーソル、全体の音量といった動画の見た目も設定できます。また、[字幕](./captions.md)をオンにし、スタイルと位置を設定し、エージェント自身で別の言語に翻訳することもできます。
+行いたい編集を、普段の言葉で伝えます(「イントロの無音部分をカットして」「ターミナルを開いたところでズームして」など)。エージェントは再レンダリングではなく、元に戻せる実際のタイムライン操作で作業します。トリム、ズーム、再生速度の範囲、注釈(テキスト、矢印、画面上の個人情報を隠すぼかし)、取り込んだオーディオトラックとそのフェード、フルスクリーンカメラのセグメントの追加と調整、クリック位置への自動ズームの追加、クリップのイン点とアウト点やクロップの編集、別のソースの映像の配置、クリップの複製・並べ替え・削除ができ、文字起こしを読んで、あなたが指している箇所を見つけます。背景、余白、角の丸み、影、デバイスフレーム、フォーマット、カメラのレイアウト、カーソル、全体の音量といった動画の見た目も設定できます。また、[字幕](./captions.md)をオンにし、スタイルと位置を設定し、エージェント自身で別の言語に翻訳することもできます。さらに、設定にない視覚エフェクトを書くこともできます。[カスタムエフェクト](./effects.md)を参照してください。
エージェントを囲むパネル:
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/editing-timeline.md
index 21c517724..7ba1db717 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ keywords:
ウェブカメラがレイアウトの枠に収まらず、フレーム全体を占める区間です。画面録画の途中に、顔出しで話すイントロを挟みたいときに便利です。録画にウェブカメラのトラックがある場合にのみ意味があります。
+### エフェクトの範囲 {#effect-regions}
+
+AI エージェントがプロジェクトのために書いた視覚エフェクトです。プロジェクトにエフェクトが入ると、フルスクリーンカメラの区間の下にその行が現れます。[カスタムエフェクト](./effects.md#in-the-editor)を参照してください。
+
### 注釈 {#annotations}
注釈には 4 つの種類があり、インスペクターの**種類**の行で選びます。種類を切り替えても、範囲の区間と画面上の位置は保たれます。
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..c565e5a63
--- /dev/null
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: カスタムエフェクト
+description: "設定にない視覚エフェクトを AI エージェントに頼めます。エージェントが GPU シェーダーを書き、OpenScreen がそれをプレビューとすべての書き出しで描画します。"
+keywords:
+ - カスタム動画エフェクト
+ - シェーダーエフェクト
+ - WGSL
+ - AI 動画エフェクト
+ - GPU エフェクト
+---
+
+# カスタムエフェクト
+
+設定に欲しい見た目がないときは、エージェントに頼みましょう。クリックごとに広がる波紋、呼吸するように明暗が変わるビネット、最後の数秒の黒へのフェードなどです。エージェントはエフェクトを小さな GPU シェーダーとして書き、OpenScreen はそれをプレビューと、MP4 と GIF のすべての書き出しで、Windows、macOS、Linux のどれでも描画します。
+
+エフェクトはエージェントから生まれます。内蔵のチャットか、Claude Code や Codex などの MCP クライアントです([AI 編集](./ai-editing.md)を参照)。エフェクトがプロジェクトに入ったら、エディターで自分で調整できます。
+
+## エフェクトを頼む {#asking-for-an-effect}
+
+見たいものと、そのタイミングを説明します。たとえば「クリックごとに波紋」「最後の 2 秒で黒にフェード、字幕も含めて」。エージェントはエフェクトを書いてタイムラインに配置し、動画を書き出さずに `getFrames` で結果を確認できます。
+
+エフェクトは、カーソルの位置と各クリックの位置、ズームとレイアウトを経た動画の中で録画とウェブカメラがどこにあるか、そして時刻を知っています。そのため、ハローをマウスに追従させたり、ズームでどこに移動していても各クリックの位置から波紋を広げたりできます。
+
+## エディターで {#in-the-editor}
+
+プロジェクトにエフェクトが入ると、タイムラインのフルスクリーンカメラの区間の下に、エフェクト専用の行が現れます。各ブロックにはエフェクトの名前が表示されます。ほかの範囲と同じように移動、サイズ変更、コピーと貼り付け、削除ができ、`Ctrl/Cmd + Z` で変更を元に戻せます。同時に再生されるエフェクトは 1 つだけです。別のエフェクトの上への貼り付けは拒否されます。
+
+ブロックをクリックするとインスペクターが開きます。
+
+- **各設定のコントロール**:エージェントがエフェクトに与えた設定ごとに、スライダー、スイッチ、色、点のいずれかが表示されます。
+- **適用先**:エフェクトを描画する場所です。
+ - **画像**(既定):録画、ウェブカメラ、カーソル、背景。注釈と字幕はその上に重なり、読みやすいままです。
+ - **テキスト**:注釈と字幕だけ。
+ - **両方**:テキストを含むフレーム全体。字幕も覆う黒へのフェードに使えます。
+- **負荷**:**軽い**、**中**、**重い**、**非常に重い**のいずれか([下記](#cost)を参照)。
+- **コード**:シェーダーを読み取り専用で表示し、**コードをコピー**できます。変更するにはエージェントに頼みます。
+
+コピーしたエフェクトを別のプロジェクトに貼り付けると、そのコードも一緒に移ります。
+
+## 負荷 {#cost}
+
+負荷はコードから見積もられます。エフェクトがピクセルごとに画像を何回読み取るかを数えます。同じコードは、どのコンピューターでも同じ段階になります。負荷を理由に拒否されることはありません。重いエフェクトほど、向いている区間は短くなります。
+
+| 段階 | 代表的なエフェクト | 向いている長さ |
+|---|---|---|
+| **軽い** | ビネット、カラーグレーディング、クリックの波紋 | 動画全体 |
+| **中** | 色収差、弱いぼかし、グリッチ | 数十秒 |
+| **重い** | 強いぼかし、ボケ | トランジション、見せ場 |
+| **非常に重い** | レイマーチング、シミュレーション | 数秒。書き出しは正確なままですが遅くなり、小さな GPU ではプレビューが遅くなることがあります |
+
+## エフェクトがコンパイルできない場合 {#if-an-effect-doesnt-compile}
+
+エージェントのコードは、エフェクトが受け入れられる前にコンパイルされます。失敗したコードはコンパイラーのエラーとともに拒否され、プロジェクトは変わりません。
+
+それでも、別のコンピューターで開いたプロジェクトが、判断の異なるコンパイラーに出会うことはあります。その場合、エフェクトは描画されず、インスペクターにエラーとともに**このコンピューターではコンパイルできません**と表示され、書き出しはそのエフェクトなしで続きます。
+
+## ほかの人のプロジェクト {#projects-from-someone-else}
+
+プロジェクトにはエフェクトのコードが含まれるため、ほかの人のプロジェクトを開くと、自分が書いていないコードが実行されます。このコードは GPU 上でのみ動作し、あなたのファイル、ネットワーク、アプリのメモリにはアクセスできません。
+
+## エージェント開発者向け {#for-agent-authors}
+
+ツールは `addEffect`、`setEffect`、`setEffectDefinition`、`getEffect` で、`removeModifier` でエフェクトを外します。完全な仕様、つまり `effect(uv)` 関数、読み取れる値、そのルールは、MCP リソース `openscreen://effects/contract` にあります。
diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md
index 0d2c10ed9..3e5ca9c4a 100644
--- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ As opções de login do ChatGPT e do GitHub Copilot foram **removidas na 1.8.0**
## Como usar o agente {#using-the-agent}
-Descreva a edição em linguagem natural — "corte o tempo morto da introdução", "dê zoom quando eu abrir o terminal". O agente trabalha com operações reais da linha do tempo, que podem ser desfeitas, e não com uma nova renderização: ele pode adicionar e ajustar recortes, zooms, regiões de velocidade, anotações (texto, setas e desfoques que escondem dados privados na tela), faixas de áudio importadas com seus fades e segmentos de Câmera em Tela Cheia, adicionar zooms automáticos nos seus cliques, editar os pontos de entrada/saída e o corte de um clipe, posicionar as imagens de outra fonte, duplicar, reordenar ou remover clipes e ler a transcrição para encontrar o trecho a que você se refere. Ele também ajusta a aparência do vídeo: fundo, margem, cantos arredondados, sombra, moldura de dispositivo, formato, o layout da câmera, o cursor e o volume geral. Ele também pode ativar as [legendas](./captions.md), estilizá-las e posicioná-las, e traduzi-las ele mesmo para outro idioma.
+Descreva a edição em linguagem natural — "corte o tempo morto da introdução", "dê zoom quando eu abrir o terminal". O agente trabalha com operações reais da linha do tempo, que podem ser desfeitas, e não com uma nova renderização: ele pode adicionar e ajustar recortes, zooms, regiões de velocidade, anotações (texto, setas e desfoques que escondem dados privados na tela), faixas de áudio importadas com seus fades e segmentos de Câmera em Tela Cheia, adicionar zooms automáticos nos seus cliques, editar os pontos de entrada/saída e o corte de um clipe, posicionar as imagens de outra fonte, duplicar, reordenar ou remover clipes e ler a transcrição para encontrar o trecho a que você se refere. Ele também ajusta a aparência do vídeo: fundo, margem, cantos arredondados, sombra, moldura de dispositivo, formato, o layout da câmera, o cursor e o volume geral. Ele também pode ativar as [legendas](./captions.md), estilizá-las e posicioná-las, e traduzi-las ele mesmo para outro idioma. E ele pode escrever um efeito visual que as configurações não oferecem: veja [Efeitos personalizados](./effects.md).
O painel em volta dele:
diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/editing-timeline.md
index 0571478e0..34c437527 100644
--- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ Uma fileira de botões de predefinição (0.5×, 1×, 1.5×, 2×, 4×) e um camp
Um trecho em que a webcam preenche o quadro em vez de ficar na caixa do layout — útil para uma introdução com você falando para a câmera no meio de uma gravação de tela. Só faz sentido quando a gravação tem uma faixa de webcam.
+### Regiões de efeito {#effect-regions}
+
+Um efeito visual que um agente de IA escreveu para o projeto. A fileira dele aparece abaixo dos trechos de Câmera em Tela Cheia assim que o projeto tem um: veja [Efeitos personalizados](./effects.md#in-the-editor).
+
### Anotações {#annotations}
Quatro tipos, escolhidos na linha **Tipo** do inspetor. Trocar o tipo mantém o trecho da região e o lugar dela na imagem.
diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..720cf00d7
--- /dev/null
+++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: Efeitos personalizados
+description: "Peça a um agente de IA um efeito visual que as configurações não oferecem. Ele escreve um shader de GPU que o OpenScreen desenha na pré-visualização e em cada exportação."
+keywords:
+ - efeitos de vídeo personalizados
+ - efeitos shader
+ - WGSL
+ - efeitos de vídeo com IA
+ - efeitos GPU
+---
+
+# Efeitos personalizados
+
+Quando as configurações não têm o visual que você procura, peça a um agente: uma onda a cada clique, uma vinheta que respira, um fade para preto nos últimos segundos. O agente escreve o efeito como um pequeno shader de GPU, e o OpenScreen o desenha na pré-visualização e em cada exportação, MP4 e GIF, no Windows, no macOS e no Linux.
+
+Os efeitos vêm de um agente: o chat integrado ou um cliente MCP como o Claude Code ou o Codex (veja [Edição com IA](./ai-editing.md)). Depois que o efeito está no projeto, você mesmo o ajusta no editor.
+
+## Pedir um efeito {#asking-for-an-effect}
+
+Descreva o que você quer ver, e quando: "uma onda a cada clique", "fade para preto nos dois últimos segundos, com as legendas". O agente escreve o efeito, coloca-o na linha do tempo e pode ver o resultado com `getFrames` sem exportar o vídeo.
+
+Um efeito sabe onde está o cursor e onde caiu cada clique, onde ficam a gravação e a webcam no vídeo depois dos zooms e do layout, e em que momento está. Assim, um halo pode seguir o mouse, e uma onda pode partir de cada clique, onde quer que o zoom o tenha levado.
+
+## No editor {#in-the-editor}
+
+Os efeitos ganham uma fileira própria na linha do tempo, abaixo dos trechos de Câmera em Tela Cheia, assim que o projeto tem um. Cada bloco leva o nome do efeito. Mova, redimensione, copie e cole ou exclua o bloco como qualquer outra região, e `Ctrl/Cmd + Z` desfaz a alteração. Só um efeito toca por vez: colar sobre outro efeito é recusado.
+
+Clique em um bloco para abrir o inspetor dele:
+
+- **Um controle para cada ajuste** que o agente deu ao efeito: um controle deslizante, um interruptor, uma cor ou um ponto.
+- **Aplica-se a**, onde o efeito é desenhado:
+ - **Imagem**, o padrão: a gravação, a webcam, o cursor e o fundo, abaixo das suas anotações e legendas, que continuam legíveis.
+ - **Textos**: só as anotações e as legendas.
+ - **Ambos**: o quadro inteiro, com o texto, para um fade para preto que também cubra as legendas.
+- **Custo**: **Leve**, **Médio**, **Pesado** ou **Muito pesado** (veja [abaixo](#cost)).
+- **Código**: o shader, somente leitura, com **Copiar código**. Para mudá-lo, peça ao agente.
+
+Um efeito copiado e colado em outro projeto leva o seu código junto.
+
+## Custo {#cost}
+
+O custo é estimado a partir do código, contando quantas vezes o efeito lê a imagem para cada pixel. O mesmo código recebe o mesmo nível em todos os computadores. Nada é recusado pelo custo: quanto mais pesado o efeito, mais curto o trecho que combina com ele.
+
+| Nível | Efeitos típicos | Combina com |
+|---|---|---|
+| **Leve** | vinheta, correção de cor, onda ao clicar | o vídeo inteiro |
+| **Médio** | aberração cromática, desfoque pequeno, glitch | algumas dezenas de segundos |
+| **Pesado** | desfoque forte, bokeh | uma transição, um momento de destaque |
+| **Muito pesado** | raymarching, simulações | alguns segundos: a exportação continua exata, mas mais lenta, e a pré-visualização pode ficar lenta em uma GPU pequena |
+
+## Se um efeito não compila {#if-an-effect-doesnt-compile}
+
+O código de um agente é compilado antes de o efeito ser aceito. Um código que falha é recusado com o erro do compilador, e o projeto não muda.
+
+Um projeto aberto em outro computador ainda pode encontrar um compilador que discorda. O efeito então não é desenhado, o inspetor dele mostra **Não compila neste computador** com o erro, e a exportação continua sem ele.
+
+## Projetos de outras pessoas {#projects-from-someone-else}
+
+Um projeto leva o código dos seus efeitos, então abrir o projeto de outra pessoa executa código que você não escreveu. Esse código roda só na GPU, sem acesso aos seus arquivos, à rede nem à memória do app.
+
+## Para autores de agentes {#for-agent-authors}
+
+As ferramentas são `addEffect`, `setEffect`, `setEffectDefinition` e `getEffect`, e `removeModifier` remove um efeito. O contrato completo, ou seja, a função `effect(uv)`, o que ela pode ler e as suas regras, é o recurso MCP `openscreen://effects/contract`.
diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md
index 346d5336a..3e885fdd8 100644
--- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ ChatGPT 和 GitHub Copilot 登录选项已**在 1.8.0 中移除**。它们的工
## 使用 AI 代理 {#using-the-agent}
-用日常语言描述你想要的编辑,例如“剪掉开头的空白”“我打开终端时放大画面”。AI 代理通过真实、可撤销的时间轴操作来完成编辑,而不是重新渲染:它可以添加和调整删减区间、缩放、速度区间、标注(文字、箭头,以及遮住屏幕上隐私信息的模糊)、导入的音轨及其淡入淡出和全屏摄像头区间,在你的点击处添加自动缩放,编辑片段的入点/出点和裁剪,放入另一个素材的画面,复制、重新排序或移除片段,还会读取转录文本,找到你所指的内容。它还能设置视频的外观:背景、边距、圆角、阴影、设备边框、画面比例、摄像头布局、光标和总音量。它还可以开启[字幕](./captions.md),设置字幕的样式和位置,并亲自把字幕翻译成另一种语言。
+用日常语言描述你想要的编辑,例如“剪掉开头的空白”“我打开终端时放大画面”。AI 代理通过真实、可撤销的时间轴操作来完成编辑,而不是重新渲染:它可以添加和调整删减区间、缩放、速度区间、标注(文字、箭头,以及遮住屏幕上隐私信息的模糊)、导入的音轨及其淡入淡出和全屏摄像头区间,在你的点击处添加自动缩放,编辑片段的入点/出点和裁剪,放入另一个素材的画面,复制、重新排序或移除片段,还会读取转录文本,找到你所指的内容。它还能设置视频的外观:背景、边距、圆角、阴影、设备边框、画面比例、摄像头布局、光标和总音量。它还可以开启[字幕](./captions.md),设置字幕的样式和位置,并亲自把字幕翻译成另一种语言。它还能写出设置里没有的视觉效果:参见[自定义效果](./effects.md)。
它周围的面板包括:
diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/editing-timeline.md
index 09120cc93..ea1c5bdf1 100644
--- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ keywords:
在这段时间里,摄像头画面会占满整个画面,而不是待在布局框里,适合在屏幕录制中间插入一段真人出镜的介绍。仅当录制内容带有摄像头轨道时才有意义。
+### 效果区间 {#effect-regions}
+
+AI 代理为项目写的视觉效果。项目里一有效果,它所在的一行就会出现在全屏摄像头区间下方:参见[自定义效果](./effects.md#in-the-editor)。
+
### 标注 {#annotations}
共有四种类型,在检查器的**类型**一行中选择。切换类型时,区间的时间范围和它在画面中的位置都会保留。
diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..16d072779
--- /dev/null
+++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: 自定义效果
+description: "让 AI 代理做出设置里没有的视觉效果。它会写一个 GPU 着色器,OpenScreen 在预览和每次导出中绘制它。"
+keywords:
+ - 自定义视频效果
+ - 着色器效果
+ - WGSL
+ - AI 视频效果
+ - GPU 效果
+---
+
+# 自定义效果
+
+如果设置里没有你想要的效果,就让代理来做:每次点击时泛起的波纹、像呼吸一样明暗变化的暗角、最后几秒淡出到黑色。代理把效果写成一个小小的 GPU 着色器,OpenScreen 会在预览以及每次导出(MP4 和 GIF)中绘制它,Windows、macOS 和 Linux 上都是如此。
+
+效果来自代理:内置聊天,或者 Claude Code、Codex 等 MCP 客户端(参见 [AI 编辑](./ai-editing.md))。效果进入项目后,你可以在编辑器里自己调整。
+
+## 请求一个效果 {#asking-for-an-effect}
+
+描述你想看到什么,以及在什么时候出现,例如“每次点击都有波纹”“最后两秒淡出到黑色,字幕也一起”。代理会写出效果、把它放到时间轴上,并且可以用 `getFrames` 查看结果,无需导出视频。
+
+效果知道光标在哪里、每次点击落在哪里,知道经过缩放和布局之后录屏和摄像头在视频中的位置,也知道当前时间。因此,光晕可以跟随鼠标,波纹可以从每次点击的位置泛起,无论缩放把它移到了哪里。
+
+## 在编辑器中 {#in-the-editor}
+
+项目里一有效果,时间轴上就会在全屏摄像头区间下方出现效果专用的一行。每个区块都显示效果的名称。可以像其他区间一样移动、调整长度、复制粘贴或删除它,`Ctrl/Cmd + Z` 可以撤销修改。同一时间只播放一个效果:粘贴到另一个效果上会被拒绝。
+
+点击区块即可打开它的检查器:
+
+- **每个设置对应一个控件**:代理为效果提供的每个设置,会显示为滑块、开关、颜色或点。
+- **作用于**,即效果绘制在哪里:
+ - **画面**(默认):录屏、摄像头、光标和背景,位于你的标注和字幕之下,文字保持清晰可读。
+ - **文字**:只作用于标注和字幕。
+ - **两者**:整个画面,包括文字,例如连字幕一起覆盖的淡出到黑色。
+- **开销**:**轻**、**中**、**重**或**很重**(参见[下文](#cost))。
+- **代码**:只读的着色器代码,附带**复制代码**按钮。要修改它,请让代理来改。
+
+把复制的效果粘贴到另一个项目时,它的代码也会一起带过去。
+
+## 开销 {#cost}
+
+开销根据代码估算:统计效果为每个像素读取画面的次数。同一份代码在任何电脑上都得到相同的级别。不会因为开销而拒绝任何效果:效果越重,适合它的片段就越短。
+
+| 级别 | 典型效果 | 适合 |
+|---|---|---|
+| **轻** | 暗角、调色、点击波纹 | 整个视频 |
+| **中** | 色差、轻微模糊、故障效果 | 几十秒 |
+| **重** | 强模糊、散景 | 一个转场、一个高光时刻 |
+| **很重** | 光线步进、模拟 | 几秒钟:导出依然准确但更慢,在性能较弱的 GPU 上预览可能会变慢 |
+
+## 效果无法编译时 {#if-an-effect-doesnt-compile}
+
+代理的代码会在效果被接受之前编译。编译失败的代码会连同编译器的错误一起被拒绝,项目保持不变。
+
+在另一台电脑上打开的项目,仍可能遇到判断不同的编译器。这时效果不会被绘制,它的检查器会显示**无法在这台电脑上编译**以及错误信息,导出则会在没有该效果的情况下继续。
+
+## 他人的项目 {#projects-from-someone-else}
+
+项目会带着其中效果的代码,所以打开别人的项目会运行不是你写的代码。这段代码只在 GPU 上运行,无法访问你的文件、网络或应用的内存。
+
+## 面向代理开发者 {#for-agent-authors}
+
+相关工具是 `addEffect`、`setEffect`、`setEffectDefinition` 和 `getEffect`,用 `removeModifier` 移除效果。完整的约定,也就是 `effect(uv)` 函数、它能读取的内容及其规则,在 MCP 资源 `openscreen://effects/contract` 中。
diff --git a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md
index 1ccdabde9..efe33494d 100644
--- a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md
+++ b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md
@@ -41,7 +41,7 @@ ChatGPT 與 GitHub Copilot 的登入選項已**在 1.8.0 中移除**。它們的
## 使用代理 {#using-the-agent}
-用一般的語言描述你要的剪輯,例如「剪掉開頭的空檔」、「我打開終端機時放大畫面」。代理會透過真實、可復原的時間軸操作來完成工作,而不是重新算繪:它可以新增與調整剪輯、縮放、速度區域、標註(文字、箭頭,以及遮住畫面上隱私資訊的模糊)、匯入的音軌及其淡入淡出與全螢幕攝影機片段,在你的點擊處加入自動縮放,編輯片段的入點與出點和裁切,放入另一個來源的畫面,複製、重新排序或移除片段,也會讀取逐字稿來找出你指的是哪一段。它也能設定影片的外觀:背景、邊距、圓角、陰影、裝置外框、畫面比例、攝影機版面、游標與整體音量。它也能開啟[字幕](./captions.md),設定字幕的樣式與位置,並自行將字幕翻譯成另一種語言。
+用一般的語言描述你要的剪輯,例如「剪掉開頭的空檔」、「我打開終端機時放大畫面」。代理會透過真實、可復原的時間軸操作來完成工作,而不是重新算繪:它可以新增與調整剪輯、縮放、速度區域、標註(文字、箭頭,以及遮住畫面上隱私資訊的模糊)、匯入的音軌及其淡入淡出與全螢幕攝影機片段,在你的點擊處加入自動縮放,編輯片段的入點與出點和裁切,放入另一個來源的畫面,複製、重新排序或移除片段,也會讀取逐字稿來找出你指的是哪一段。它也能設定影片的外觀:背景、邊距、圓角、陰影、裝置外框、畫面比例、攝影機版面、游標與整體音量。它也能開啟[字幕](./captions.md),設定字幕的樣式與位置,並自行將字幕翻譯成另一種語言。它也能寫出設定裡沒有的視覺效果:請參閱[自訂效果](./effects.md)。
它周圍的面板包括:
diff --git a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/editing-timeline.md b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/editing-timeline.md
index ec9ef423f..331af98b9 100644
--- a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/editing-timeline.md
+++ b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/editing-timeline.md
@@ -78,6 +78,10 @@ keywords:
在這段範圍內,網路攝影機會佔滿整個畫面,而不是待在版面配置的框框裡,適合在螢幕錄影中間穿插一段真人出鏡的開場。只有在錄影含有網路攝影機軌道時才有意義。
+### 效果區域 {#effect-regions}
+
+AI 代理為專案寫的視覺效果。專案裡一有效果,它所在的那一列就會出現在全螢幕攝影機區域下方:請參閱[自訂效果](./effects.md#in-the-editor)。
+
### 標註 {#annotations}
共有四種類型,在檢查器的**類型**一列中選擇。切換類型時會保留區域的時間範圍,以及它在畫面中的位置。
diff --git a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/effects.md b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/effects.md
new file mode 100644
index 000000000..e3f2cb5e1
--- /dev/null
+++ b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/effects.md
@@ -0,0 +1,64 @@
+---
+id: effects
+title: 自訂效果
+description: "請 AI 代理做出設定裡沒有的視覺效果。它會寫一個 GPU 著色器,OpenScreen 會在預覽和每次匯出中繪製它。"
+keywords:
+ - 自訂影片效果
+ - 著色器效果
+ - WGSL
+ - AI 影片效果
+ - GPU 效果
+---
+
+# 自訂效果
+
+如果設定裡沒有你想要的效果,就請代理來做:每次點擊時泛起的波紋、像呼吸一樣明暗變化的暗角、最後幾秒淡出成黑色。代理會把效果寫成一個小小的 GPU 著色器,OpenScreen 會在預覽以及每次匯出(MP4 和 GIF)中繪製它,Windows、macOS 和 Linux 上都是如此。
+
+效果來自代理:內建聊天,或是 Claude Code、Codex 等 MCP 用戶端(請參閱 [AI 剪輯](./ai-editing.md))。效果進入專案後,你可以在編輯器裡自行調整。
+
+## 請求一個效果 {#asking-for-an-effect}
+
+描述你想看到什麼,以及在什麼時候出現,例如「每次點擊都有波紋」、「最後兩秒淡出成黑色,字幕也一起」。代理會寫出效果、把它放到時間軸上,並且可以用 `getFrames` 查看結果,不必匯出影片。
+
+效果知道游標在哪裡、每次點擊落在哪裡,知道經過縮放和版面配置之後,螢幕錄影和攝影機在影片中的位置,也知道目前的時間。因此,光暈可以跟著滑鼠移動,波紋可以從每次點擊的位置泛起,無論縮放把它移到了哪裡。
+
+## 在編輯器中 {#in-the-editor}
+
+專案裡一有效果,時間軸上就會在全螢幕攝影機區域下方出現效果專用的一列。每個區塊都會顯示效果的名稱。你可以像其他區域一樣移動、調整長度、複製貼上或刪除它,`Ctrl/Cmd + Z` 可以復原修改。同一時間只會播放一個效果:貼到另一個效果上會被拒絕。
+
+點擊區塊即可開啟它的檢查器:
+
+- **每個設定對應一個控制項**:代理為效果提供的每個設定,會顯示為滑桿、開關、顏色或點。
+- **作用於**,也就是效果繪製在哪裡:
+ - **畫面**(預設):螢幕錄影、攝影機、游標和背景,位於你的標註和字幕之下,文字保持清楚可讀。
+ - **文字**:只作用於標註和字幕。
+ - **兩者**:整個畫面,包括文字,例如連字幕一起覆蓋的淡出成黑色。
+- **開銷**:**輕**、**中**、**重**或**很重**(請參閱[下文](#cost))。
+- **程式碼**:唯讀的著色器程式碼,附有**複製程式碼**按鈕。要修改它,請代理來改。
+
+把複製的效果貼到另一個專案時,它的程式碼也會一起帶過去。
+
+## 開銷 {#cost}
+
+開銷是根據程式碼估算的:計算效果為每個像素讀取畫面的次數。同一份程式碼在任何電腦上都會得到相同的等級。不會因為開銷而拒絕任何效果:效果越重,適合它的片段就越短。
+
+| 等級 | 典型效果 | 適合 |
+|---|---|---|
+| **輕** | 暗角、調色、點擊波紋 | 整部影片 |
+| **中** | 色差、輕微模糊、故障效果 | 幾十秒 |
+| **重** | 強烈模糊、散景 | 一個轉場、一個精彩時刻 |
+| **很重** | 光線步進、模擬 | 幾秒鐘:匯出依然準確但較慢,在效能較弱的 GPU 上預覽可能會變慢 |
+
+## 效果無法編譯時 {#if-an-effect-doesnt-compile}
+
+代理的程式碼會在效果被接受之前編譯。編譯失敗的程式碼會連同編譯器的錯誤一起被拒絕,專案保持不變。
+
+在另一台電腦上開啟的專案,仍可能遇到判斷不同的編譯器。這時效果不會被繪製,它的檢查器會顯示**無法在這台電腦上編譯**以及錯誤訊息,匯出則會在沒有該效果的情況下繼續。
+
+## 他人的專案 {#projects-from-someone-else}
+
+專案會帶著其中效果的程式碼,所以開啟別人的專案會執行不是你寫的程式碼。這段程式碼只在 GPU 上執行,無法存取你的檔案、網路或應用程式的記憶體。
+
+## 給代理開發者 {#for-agent-authors}
+
+相關工具是 `addEffect`、`setEffect`、`setEffectDefinition` 和 `getEffect`,用 `removeModifier` 移除效果。完整的規範,也就是 `effect(uv)` 函式、它能讀取的內容及其規則,在 MCP 資源 `openscreen://effects/contract` 中。
diff --git a/website/sidebars.ts b/website/sidebars.ts
index c69ccbea7..b66c0d03c 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -18,6 +18,7 @@ const sidebars: SidebarsConfig = {
"editing-timeline",
"captions",
"ai-editing",
+ "effects",
"export",
"cli",
],