# Media identifiers in Port OS
## Media IDs

Media IDs are a standardized identifier that Port OS uses to represent media across YouTube, Spotify, and other media providers. The string format is defined in [MediaId.yaml](https://github.com/portpowered/portos-monolith/blob/main/api/common-schemas/MediaId.yaml).

Use media URIs to identify exact provider resources. For example:

`portos-media://portoperatingsystem.com/spotify/audio/track/123456`

Breaking this down:
- portos-media:// - The protocol identifier for Port OS media
- portoperatingsystem.com - The authority that manages the media protocol
- spotify - The service providing the media content
- audio - The type of media content
- track - The provider resource kind
- 123456 - The unique resource identifier within that service

This format identifies a provider resource independently of the output device. A catalog result does not establish that every output can play it; choose a route with a tested mapping for that provider.

## Playing media

To play media:

1. Find an endpoint and route that support the selected provider/resource and playback operation.
2. Copy the exact media ID from search or library discovery into the route's declared message.
3. Read fresh device state after dispatch. Acceptance alone does not prove audible playback.

## Port OS media URI protocol

The Port OS media URI format follows this BNF grammar:
```text
media-uri    ::= "portos-media://" authority "/" service "/" type "/" resource-kind "/" resource-id
authority    ::= "portoperatingsystem.com"
service      ::= "spotify" | "youtube" | "netflix" | other-service-name
type         ::= "audio" | "video" | "image"
resource-kind ::= "track" | "playlist" | "album" | "artist" | "show" | "episode" | "video" | "channel" | other-resource-kind
resource-id  ::= provider-defined-escaped-id
```

Resource IDs follow the provider's syntax and are escaped as one URI path
segment. YouTube IDs can contain letters, digits, hyphens and underscores;
preserve their exact spelling and case by copying the returned identity.

Provider API and SDK versions are independent of media identity and do not
appear in this URI. Spotify's cutover is breaking: old versioned media IDs and
native spotify: IDs are replaced in first-party results. Existing providers
retain their input contracts until explicitly migrated. Previously issued
`portpowered.com` authorities remain readable and normalize to the current
authority; preserve the provider and resource ID during migration.

## YouTube identities

YouTube and YouTube Music use the same `youtube` provider. A video uses
`portos-media://portoperatingsystem.com/youtube/video/video/VIDEO_ID`.
Its publishing channel uses `youtube/video/channel/CHANNEL_ID`; a channel is
creator metadata and is not automatically a playable song or musician identity.
The search adapter omits album metadata when YouTube supplies
none. An exact video identity does not imply a downloadable audio URL or a
compatible playback implementation on Alexa or Sonos.

## Spotify resources

| Resource kind | Use |
| --- | --- |
| track | Play an exact song |
| playlist | Read items or play a playlist context |
| album | Read tracks or play an album context |
| artist | Search or inspect an artist |
| show | Read episodes before choosing one |
| episode | Play an exact episode when the target supports it |
| audiobook / chapter | Reserved identity until traversal/playback is advertised |

Copy a selected ID returned by search or library discovery; an ID is not a
search phrase. Preserve the selected provider and recording. Similar titles
from Spotify and YouTube are separate resources.

A group must declare native playback support; merely containing speakers does
not make it a synchronized speaker group. Choose the target's compatible route
and send one native command, then read fresh state to confirm the outcome.