# 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: `source:id` tokens separated by commas.                     |

Rules for `list=`:

- Each token is source:id, where source is one of the names below and id is that source’s own identifier - not a full URL.
- Separate tokens with a comma. No spaces or line breaks anywhere in the list.
- At most 500 tokens. Above about 250 the link becomes unwieldy for 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      | Token              | Id                                                                  | Example token                         |
| ----------- | ------------------ | ------------------------------------------------------------------- | ------------------------------------- |
| YouTube     | `youtube:<id>`     | Exactly 11 characters from A-Z, a-z, 0-9, _ and -                   | `youtube:dQw4w9WgXcQ`                 |
| SoundCloud  | `soundcloud:<id>`  | The permalink path: artist/track, or artist/sets/name for a set     | `soundcloud:artist/track-name`        |
| Vimeo       | `vimeo:<id>`       | The numeric video id; an unlisted video may append /<hash>          | `vimeo:771351262`                     |
| TikTok      | `tiktok:<id>`      | The author handle without @, a slash, then the 10-25 digit video id | `tiktok:username/7300000000000000000` |
| Dailymotion | `dailymotion:<id>` | x followed by 2-12 lowercase letters or digits                      | `dailymotion: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 ids you have verified exist, by searching the web or opening the source page. Never invent an id: one wrong id invalidates the whole link.
2. If a track cannot be verified, leave it out rather than guess.
3. Prefer YouTube unless asked otherwise; it has the widest catalogue.
4. At most 500 tracks.
5. Reply with the bare link on its own line - no Markdown link syntax, backticks or angle brackets, and no line breaks inside it.
6. Titles and artwork are not part of the link. Cuepile fetches them from the source when the link is opened.

## Complete example

Single source, two tracks.

```
https://cuepile.com/share#v=1&n=Cuepile+demo&list=youtube:dQw4w9WgXcQ,youtube: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