# Cuepile share link format

A Cuepile playlist is a single URL. Opening it in a browser rebuilds the
playlist and starts playing. This document is the specification for writing
one - by hand, or by an AI assistant asked to build a playlist.

Version 1. This is the only version at the moment.

## Shape

```
https://cuepile.com/share#v=1&n=<NAME>&list=<TOKENS>
```

Everything after `#` is the playlist. The `#` is mandatory - it is a URL
fragment, not a query string. `?` does not work.

| Part    | Meaning                                                                            |
| ------- | ---------------------------------------------------------------------------------- |
| `v=1`   | Format version. Always `1`.                                                        |
| `n=`    | Playlist name, URL-encoded. Spaces as `+` or `%20`. Max 200 characters. Optional.  |
| `list=` | Tracks in play order: `prefix:id` or `prefix:id:title` tokens separated by commas. |

Rules for `list=`:

- Each token is prefix:id or prefix:id:title. The prefix is a source’s short code (below) or its full name; the id is that source’s own identifier - not a full URL.
- The title is optional. It overrides the video’s own title - useful when that title is missing something, like a year. URL-encode it: spaces as + or %20, commas as %2C. Longer than 60 characters is cut off.
- Separate tokens with a comma. No spaces or line breaks anywhere in the list.
- At most 500 tokens. Keep to about 250 without titles, or about 100 with them - beyond that the link outgrows messaging apps and QR codes.
- Every token must be valid. If any single token fails, the whole link is refused - Cuepile never opens a partial playlist.

## Sources and ids

| Source      | Prefix                 | Id                                                                  | Example token                    |
| ----------- | ---------------------- | ------------------------------------------------------------------- | -------------------------------- |
| YouTube     | `y:` or `youtube:`     | Exactly 11 characters from A-Z, a-z, 0-9, _ and -                   | `y:dQw4w9WgXcQ`                  |
| SoundCloud  | `s:` or `soundcloud:`  | The permalink path: artist/track, or artist/sets/name for a set     | `s:artist/track-name`            |
| Vimeo       | `v:` or `vimeo:`       | The numeric video id; an unlisted video may append /<hash>          | `v:771351262`                    |
| TikTok      | `t:` or `tiktok:`      | The author handle without @, a slash, then the 10-25 digit video id | `t:username/7300000000000000000` |
| Dailymotion | `d:` or `dailymotion:` | x followed by 2-12 lowercase letters or digits                      | `d:x95qxni`                      |

Where the id comes from:

- **YouTube**: The v= parameter of a watch URL, or the path of a youtu.be link. `https://www.youtube.com/watch?v=dQw4w9WgXcQ` -> `dQw4w9WgXcQ`
- **SoundCloud**: The path of the track page. `https://soundcloud.com/artist/track-name` -> `artist/track-name`
- **Vimeo**: The number in the video URL. `https://vimeo.com/771351262` -> `771351262`
- **TikTok**: The handle and the video number from the video URL. `https://www.tiktok.com/@username/video/7300000000000000000` -> `username/7300000000000000000`
- **Dailymotion**: The last path segment of the video URL. `https://www.dailymotion.com/video/x95qxni` -> `x95qxni`

## Validation patterns

These are the exact regular expressions Cuepile checks each id against.

```
youtube      ^[A-Za-z0-9_-]{11}$
soundcloud   ^[\w.-]+\/(?:sets\/)?[\w.-]+$
vimeo        ^\d+(?:\/[0-9a-f]{6,12})?$
tiktok       ^[\w.-]+\/\d{10,25}$
dailymotion  ^x[a-z0-9]{2,12}$
```

## Guidance for AI assistants

1. Use only real, verified ids or paths, found by searching the web or opening the source page. Never invent an id: one wrong token invalidates the whole link.
2. If an item cannot be reliably verified, leave it out rather than guess.
3. Keep the tracks in the order that was asked for.
4. Prefer YouTube unless asked otherwise; it has the widest catalogue.
5. Add a :title only where the video’s own title misses the point - a year, the real song name. Keep it under about 30 characters and omit it everywhere else; every title makes the link longer.
6. Limits: prefer 250 tracks or fewer without titles, 100 or fewer when titles are used. 500 is the absolute maximum and must never be exceeded.
7. Reply with the bare link on its own line - no Markdown link syntax, backticks or angle brackets, and no line breaks inside it.
8. Artwork is never part of the link, and titles only when a token chooses one - everything else Cuepile fetches from the source when the link is opened.

## Complete example

Single source, two tracks, short prefixes.

```
https://cuepile.com/share#v=1&n=Cuepile+demo&list=y:dQw4w9WgXcQ,y:9bZkp7q19f0
```

More examples, including ones that fail and why: https://cuepile.com/share/examples.md

Machine-readable version of this document: https://cuepile.com/share/schema.json