# Practice lists: build a link that fills a PianoKitty list (for AI agents)

> You write a practice plan as plain text, one item per line. You wrap it in one
> link. The person opens the link, checks the text and presses Add. This page is
> generated from the same code the app uses. Exercise URLs: /help/params.md and
> /help/recipes.md.

## What this does and who clicks what

- You cannot save a list. You only produce a link.
- The person must be logged in to PianoKitty and press **Add**. Opening the link saves nothing.
- The app shows your text in the Quick add box with this notice: "Text came from a link. Check it before adding."
- If the person is logged out, they log in first and the text travels through the login. This is reliable up to about 2500 characters of raw text. For longer text, tell the person to log in before they open the link.

## The link

```text
https://pianokitty.com/list/create?add=<encodeURIComponent(text)>
```

- Percent-encode the whole text with `encodeURIComponent` (or the same rules). A newline is `%0A`, a space is `%20`, `&` is `%26`, `#` is `%23`.
- Encode the text once, as a whole. A `%2C` inside an exercise address becomes `%252C`. That is correct.
- To add to a list that already exists, use `https://pianokitty.com/list/<id>/edit?add=…`. Do this only if the person gave you that list's address.
- The app reads at most 8000 characters of text and a list holds at most 200 items. Lines that do not fit are skipped and the app tells the person how many.
- Keep the whole finished link under about 6000 characters, or the server may refuse to open it. Plain, short lists work best. Aim for 3 to 10 items.

## One line is one item

| Part | Write | What the app does |
| --- | --- | --- |
| List marker | `- `, `* `, `• `, `1. ` or `1) ` at the start of the line | Removed. |
| Link | Any absolute `https://…` address, anywhere in the line | Becomes a link on the item, typed by its address (table below). Up to 20 per item. |
| Tempo | `80 bpm`, `tempo: 80` or `tempo 80` | Sets the item tempo (20–300) and switches the metronome on for that item. There is no separate metronome word. |
| Time | `10 min`, `10 mins`, `10 minutes` or `10m` | Sets a countdown of 0–600 minutes. When it runs out the list moves to the next item. |
| Title | The text before the first `.` | The item name, up to 200 characters. No `.` in the line: all the text is the title. |
| Description | The text after the first `.` | Shown under the title. Basic Markdown (bold, italics), up to 4000 characters. |

Nothing else is read. There is no active flag and there are no link labels.

## Link types

Each link is typed by its address. Always write absolute `https://` addresses. Relative ones such as `/app?…` are not recognized.

| Address | Item type | In the list player |
| --- | --- | --- |
| `youtube.com`, `youtu.be`, `vimeo.com` | video | Plays in place. |
| Ends in `.png`, `.jpg`, `.jpeg`, `.webp`, `.avif`, `.gif`, `.bmp` or `.svg` (a query string after it is fine) | image | Shown on the practice screen. Any public https image address works as a custom image. |
| Ends in `.pdf` | file | An **Open file** button. |
| `https://pianokitty.com/app?subject=…` (built from /help/params.md or /help/recipes.md) | exercise | Turned into a real PianoKitty exercise when the person adds the line. Plays inside the list. |
| Anything else | other | An **Open link** button. |

Melody exercises (`subject=melodies`) stay plain links, because they play on /repeat.

## Pitfalls

- One item per line. Blank lines are ignored. A description cannot span lines.
- The first `.` ends the title. Write "Op 28", not "Op. 28". Avoid "e.g.", "No. 3" and "10.30" in a title. A `.` inside a web address is fine.
- A number followed by `min`, `mins`, `minutes` or `m` is read as minutes. A number followed by `bpm` is read as tempo. Write other quantities in words, for example "bars 5 to 8".
- Put a space before and after each address. Do not use Markdown link syntax like `[text](https://…)`: the brackets stay in the title.
- Tempo outside 20–300 is ignored. Time above 600 is ignored.
- Never invent a `d=` value. Exercise links use `subject=…` parameters only.

## Limits

| What | Limit |
| --- | --- |
| Text read from the link | 8000 characters |
| Items in one list | 200 |
| Title | 200 characters |
| Description | 4000 characters |
| Links per item | 20 |
| Tempo | 20–300 bpm |
| Time | 0–600 minutes |
| Text that is safe when the person is logged out | about 2500 characters |

## Worked examples

### A. Beginner week: scales, a video, tempo and minutes

Five items for one week. Three are PianoKitty exercises, one is a video. Replace VIDEO_ID with a real YouTube link the person gave you.

Plain text:

```text
- Monday: C major scale, note by note. Slow and even, no tension. https://pianokitty.com/app?subject=scales&key=C&mode=major&voicing=singleNotes&seq=inOrder 60 bpm 10 min
- Tuesday: natural minor scale. Listen to how it differs from major. https://pianokitty.com/app?subject=scales&mode=naturalMinor&voicing=singleNotes&seq=inOrder 60 bpm 10 min
- Wednesday: watch the posture video. Then sit like that. https://www.youtube.com/watch?v=VIDEO_ID 5 min
- Thursday: major pentatonic scale. https://pianokitty.com/app?subject=scales&mode=pentatonicMajor&voicing=singleNotes&seq=inOrder 70 bpm 10 min
- Friday: play all of it once more. Then rest. 15 min
```

The final link:

https://pianokitty.com/list/create?add=-%20Monday%3A%20C%20major%20scale%2C%20note%20by%20note.%20Slow%20and%20even%2C%20no%20tension.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dscales%26key%3DC%26mode%3Dmajor%26voicing%3DsingleNotes%26seq%3DinOrder%2060%20bpm%2010%20min%0A-%20Tuesday%3A%20natural%20minor%20scale.%20Listen%20to%20how%20it%20differs%20from%20major.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dscales%26mode%3DnaturalMinor%26voicing%3DsingleNotes%26seq%3DinOrder%2060%20bpm%2010%20min%0A-%20Wednesday%3A%20watch%20the%20posture%20video.%20Then%20sit%20like%20that.%20https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVIDEO_ID%205%20min%0A-%20Thursday%3A%20major%20pentatonic%20scale.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dscales%26mode%3DpentatonicMajor%26voicing%3DsingleNotes%26seq%3DinOrder%2070%20bpm%2010%20min%0A-%20Friday%3A%20play%20all%20of%20it%20once%20more.%20Then%20rest.%2015%20min

### B. Sight-reading and theory: an image, a PDF and a Markdown description

Three items. Replace the example.com addresses with real public links.

Plain text:

```text
Read the chord chart. Name every chord **before** you play it. https://example.com/chart.png 10 min
Key signatures sheet. Fill it in, then *check each one at the piano*. https://example.com/key-signatures.pdf 15 min
Sight-reading card. Play it twice: first slowly, then **in time**. https://example.com/sight-reading-1.png 60 bpm 5 min
```

The final link:

https://pianokitty.com/list/create?add=Read%20the%20chord%20chart.%20Name%20every%20chord%20**before**%20you%20play%20it.%20https%3A%2F%2Fexample.com%2Fchart.png%2010%20min%0AKey%20signatures%20sheet.%20Fill%20it%20in%2C%20then%20*check%20each%20one%20at%20the%20piano*.%20https%3A%2F%2Fexample.com%2Fkey-signatures.pdf%2015%20min%0ASight-reading%20card.%20Play%20it%20twice%3A%20first%20slowly%2C%20then%20**in%20time**.%20https%3A%2F%2Fexample.com%2Fsight-reading-1.png%2060%20bpm%205%20min

### C. Chord drills with the metronome: 20 minutes in total

Four exercises, five minutes each. Each has its own tempo and the metronome starts by itself.

Plain text:

```text
1. Major triads, all keys. Root position only. https://pianokitty.com/app?subject=chords&voicing=triads&ct=0&inv=0 60 bpm 5 min
2. Major and minor triads mixed. Listen to the difference. https://pianokitty.com/app?subject=chords&voicing=triads&ct=0%2C1&inv=0 70 bpm 5 min
3. Triads through all inversions. Keep the hand shape. https://pianokitty.com/app?subject=chords&voicing=triads&ct=0%2C1&inv=0%2C1%2C2 80 bpm 5 min
4. Core seventh chords. Slow and relaxed. https://pianokitty.com/app?subject=chords&voicing=sevenths&ct=6%2C7%2C8 60 bpm 5 min
```

The final link:

https://pianokitty.com/list/create?add=1.%20Major%20triads%2C%20all%20keys.%20Root%20position%20only.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dchords%26voicing%3Dtriads%26ct%3D0%26inv%3D0%2060%20bpm%205%20min%0A2.%20Major%20and%20minor%20triads%20mixed.%20Listen%20to%20the%20difference.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dchords%26voicing%3Dtriads%26ct%3D0%252C1%26inv%3D0%2070%20bpm%205%20min%0A3.%20Triads%20through%20all%20inversions.%20Keep%20the%20hand%20shape.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dchords%26voicing%3Dtriads%26ct%3D0%252C1%26inv%3D0%252C1%252C2%2080%20bpm%205%20min%0A4.%20Core%20seventh%20chords.%20Slow%20and%20relaxed.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dchords%26voicing%3Dsevenths%26ct%3D6%252C7%252C8%2060%20bpm%205%20min

### D. Teacher warm-up routine: five items, 20 minutes in total

A fixed order for the first part of a lesson. The timers move the list on by themselves.

Plain text:

```text
- Posture and breathing. Sit tall, hands loose on the lap. 2 min
- Five-finger warm-up. C position, both hands, slowly. 3 min
- Scale of the week: harmonic minor. https://pianokitty.com/app?subject=scales&mode=harmonicMinor&voicing=singleNotes&seq=inOrder 5 min
- Chords of the week: white-key triads. https://pianokitty.com/app?subject=chords&voicing=triads&ct=0%2C1&bn=0%2C2%2C4%2C5%2C7%2C9%2C11 70 bpm 5 min
- Sight-reading. One line, no stopping, even if you slip. 5 min
```

The final link:

https://pianokitty.com/list/create?add=-%20Posture%20and%20breathing.%20Sit%20tall%2C%20hands%20loose%20on%20the%20lap.%202%20min%0A-%20Five-finger%20warm-up.%20C%20position%2C%20both%20hands%2C%20slowly.%203%20min%0A-%20Scale%20of%20the%20week%3A%20harmonic%20minor.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dscales%26mode%3DharmonicMinor%26voicing%3DsingleNotes%26seq%3DinOrder%205%20min%0A-%20Chords%20of%20the%20week%3A%20white-key%20triads.%20https%3A%2F%2Fpianokitty.com%2Fapp%3Fsubject%3Dchords%26voicing%3Dtriads%26ct%3D0%252C1%26bn%3D0%252C2%252C4%252C5%252C7%252C9%252C11%2070%20bpm%205%20min%0A-%20Sight-reading.%20One%20line%2C%20no%20stopping%2C%20even%20if%20you%20slip.%205%20min

## A prompt for the person to paste into a chatbot

```text
Make a piano practice list for: [who it is for, their level, what they practice].
Time per day: [minutes]. Number of days: [days].

Output ONE link and nothing else. Build the link like this:

1. Write the list as plain text, one practice item per line. Start a line with "- ".
2. Start the link with https://pianokitty.com/list/create?add= and add the whole text after it, percent-encoded (newline = %0A, space = %20).
3. On a line you may add: a tempo like "80 bpm", a time like "10 min", and links that start with https://.
4. The text before the first "." is the title. Use "." only to start a description. Write "Op 28", never "Op. 28".
5. For PianoKitty exercises use links like https://pianokitty.com/app?subject=scales&key=C&mode=major (more in https://pianokitty.com/help/recipes.md and https://pianokitty.com/help/params.md).
6. Use a YouTube, PDF or image link only if I gave it to you. Do not invent web addresses.
7. Keep the text under 2500 characters and under 200 lines.
8. Do not put names, e-mail addresses or passwords in the text.

More rules and examples: https://pianokitty.com/help/lists.md
```

## Do not

- Do not put secrets, passwords, tokens or personal data (names of children, e-mail addresses) in the text. The link is logged by the server and kept in the chat.
- Do not invent web addresses. Use only links the person gave you, links from /help/recipes.md and /help/params.md, and addresses you know exist.
- Use `https://` only. Other schemes are not accepted.
- Do not say the list is saved. It is saved when the person presses Add.
- Do not output the text without encoding it. The link must work when it is clicked.
