Basic rules
- The Scheme name is case insensitive. We recommend using lowercase
oopsplayer://consistently. - URL encode query parameter values, especially nested URLs, non-ASCII text, spaces,
&,?, and#. Supply each parameter only once. - Media URLs can use
http,https,rtmp,rtsp,rtp,udp, ormms. Playback depends on the media format and network conditions. - The example domains are placeholders. When a website opens the Scheme, the browser may ask the user to confirm opening the app.
Play network media
We recommend the x-callback-url route. Only url is required.
oopsplayer://x-callback-url/play?url=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv
| Parameter | Required | Description |
|---|---|---|
url | Yes | Media URL. Encode the complete URL as a single query parameter value. |
name | No | Name shown in the player and used to identify the file extension. The legacy title parameter also works; name takes precedence when both are present. |
position | No | Starting position in seconds, as a non-negative integer. Playback starts at 0 when omitted. |
sub | No | HTTP or HTTPS external subtitle URL. The player will try to select it automatically. |
User-Agent | No | User-Agent used when requesting the media URL. Match the parameter name’s capitalization exactly. |
x-success | No | Calling app’s Scheme URL to open when the user closes the player. See the next section. |
With subtitles, a start position, and User-Agent
oopsplayer://x-callback-url/play?url=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv&name=Movie.mkv&position=915&sub=https%3A%2F%2Fmedia.example.com%2Fsubtitle.ass&User-Agent=MyApp
Return to the calling app after closing the player
When x-success is provided and the user closes the player, OopsPlayer appends lastPlayedUrl and position to that URL’s existing query parameters. position is the non-negative integer number of seconds at closing. The calling app must register its own Scheme to receive the callback.
oopsplayer://x-callback-url/play?url=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv&x-success=myapp%3A%2F%2Fplayback-done%3Fsource%3Doops
Example callback:
myapp://playback-done?source=oops&lastPlayedUrl=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv&position=120
This callback is sent only after playback has actually opened and the user closes the player. x-success must use the calling app’s custom Scheme; HTTP, HTTPS, file, and OopsPlayer’s own Scheme are not accepted.
Import an Emby server
Opening the link shows a configuration preview in OopsPlayer. The server is saved only after the user confirms. Passwords use the existing Keychain storage mechanism, and imported servers are stored locally by default.
oopsplayer://importserver?type=emby&address=https%3A%2F%2Femby.example.com%3A443%2Femby&name=Home%20Emby&username=alice&password=example
| Parameter | Required | Description |
|---|---|---|
type | Yes | Currently, only emby is supported. |
address | Yes | Full HTTP or HTTPS address. It may include a port and base path. |
username | Yes | Emby login username. |
password | No | Login password. You can also enter it in the app after importing. |
name | No | Display name for the server. Defaults to the hostname when omitted. |
addressNname + addressN | No | Provide a backup route name and HTTP(S) address as a pair, where N ranges from 1 to 20. For example, address1name and address1. |
Example with a backup route
oopsplayer://importserver?type=emby&address=https%3A%2F%2Femby.example.com&username=alice&address1name=Backup&address1=https%3A%2F%2Fbackup.example.com
Links containing passwords may appear in browser history, clipboards, or logs kept by the calling app. Share them only through trusted channels and enter passwords in the app when possible. Imports remain subject to OopsPlayer’s current server limit; an Emby server with the same address will not be added twice.