# Eggtimer.app recipes and community contributions

A recipe is a small JSON file describing a timer. It contains data only; it cannot run JavaScript or load CSS, fonts, images, or network endpoints. Open Build your own for its simple editor (basic recipes) or paste JSON, or copy its builder prompt into an LLM. The same validator checks every imported recipe.

## Version 1 contract

- version: 1 (required).
- title: 1–80 characters; default My timer.
- author: 1–60 characters; default You. Attribution travels with the recipe.
- display: digits, ring, or bar; default digits.
- theme: optional object containing any of paper, panel, ink, muted, line, accent, white, highlight. Every supplied value is a six-digit hex color. Missing colors use the Plain palette.
- steps: 1–12 objects, each with a positive integer seconds and optional 1–60 character label.
- cycles: integer 1–12, default 1. Repeats the complete step sequence.
- autoAdvance: boolean, default true. If false, wait for a click between steps.
- completion: optional object with message (1–160 characters), sound (boolean, default true), and webhook (boolean, default false). webhook=true suggests connecting an action; it does not grant permission or send a request.
- The total seconds across all steps and cycles must be at most 315576000. Unknown properties are rejected.

## Version 2 interval recipes

Version 1 remains supported unchanged. Use version: 2 for intervals with 1–32 steps; seconds may be fractional (at least 0.1); each step may have repeat (integer 1–32, default 1). At most 512 repetitions may be expanded across cycles. stepSound (boolean, default false) plays a short cue at each repetition boundary, with a three-beep cue at a new step group. repeatLabel (1–20 characters, default Repeat) names the repetition counter. note (up to 320 characters) provides setup instructions. Other fields and the total duration limit are unchanged. Advanced recipes use the JSON editor, and can be exported/shared like basic recipes. Timer timing uses the fractional values; webhook duration_seconds is rounded to the nearest whole second (minimum 1). If an audible interval deadline is missed by more than one second, the recipe pauses and requires a restart.

The Beep Test · 20m starter uses a 10-second setup followed by 21 progressively faster levels and 247 shuttles. It starts at 8.5 km/h, increasing 0.5 per level. Individual intervals are 72 / speed_kph seconds. This is practice pacing, not certified assessment audio or automatic scoring. Keep the app visible and test audio first. Protocol references: [Léger et al., 1988](https://pubmed.ncbi.nlm.nih.gov/3184250/) and the [21-level shuttle schedule](https://www.topendsports.com/testing/beep-table.htm).

The machine-readable contract is [recipe.schema.json](https://eggtimer.app/recipe.schema.json). The total-duration rule is also checked by the runtime.

## Minimal example

```json
{"version":1,"title":"Tea, then breathe","author":"You","steps":[{"label":"Steep","seconds":180},{"label":"Breathe","seconds":60}],"display":"ring","completion":{"message":"Tea is ready.","sound":true,"webhook":true}}
```

## Share, remix, and embed

Use & save remix stores a copy in this browser. Export JSON downloads a portable file. Copy link creates a URL fragment with recipe= followed by base64url-encoded UTF-8 JSON. The recipient sees a preview and presses Start; it does not synchronize sessions. Their webhook connection is never imported. Copy embed produces an iframe that shows the timer controls with the surrounding site hidden.

The fragment format is #recipe=BASE64URL. Embedded links also include &embed=1. Prefer using the editor's copy buttons rather than asking an LLM to hand-compute base64. An LLM can return valid JSON for the recipient to paste into Remix → JSON / paste from an LLM.

The starter gallery contains original examples, not fabricated community submissions. Saved remixes appear in that browser's gallery. Share links wherever a community already gathers. A public submission registry, arbitrary display plugins, account sync, and a paid marketplace are not part of this release.