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.

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:

Find an endpoint and route that support the selected provider/resource and playback operation.
Copy the exact media ID from search or library discovery into the route's declared message.
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.