mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-09 20:17:20 -05:00
196 lines
11 KiB
HTML
196 lines
11 KiB
HTML
<!doctype html>
|
|
<html lang="en" class="dark">
|
|
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<title>Paths and playback events — Vyla</title>
|
|
<meta name="description" content="The complete Stream API playback contract, unified for movies and TV episodes." />
|
|
<meta name="keywords"
|
|
content="Stream API paths, playback events, SSE events, API endpoints, movie API, TV API, streaming endpoints" />
|
|
<link rel="canonical" href="https://vyla.cc/stream-api/paths.html" />
|
|
|
|
<!-- Open Graph / Facebook -->
|
|
<meta property="og:type" content="website" />
|
|
<meta property="og:url" content="https://vyla.cc/stream-api/paths.html" />
|
|
<meta property="og:title" content="Paths and playback events — Vyla" />
|
|
<meta property="og:description"
|
|
content="The complete Stream API playback contract, unified for movies and TV episodes." />
|
|
<meta property="og:image" content="https://vyla.cc/assets/images/thumbnail.png" />
|
|
<meta property="og:site_name" content="Vyla" />
|
|
|
|
<!-- Twitter -->
|
|
<meta property="twitter:card" content="summary_large_image" />
|
|
<meta property="twitter:url" content="https://vyla.cc/stream-api/paths.html" />
|
|
<meta property="twitter:title" content="Paths and playback events — Vyla" />
|
|
<meta property="twitter:description"
|
|
content="The complete Stream API playback contract, unified for movies and TV episodes." />
|
|
<meta property="twitter:image" content="https://vyla.cc/assets/images/thumbnail.png" />
|
|
<meta property="twitter:site" content="@vylaentertainment" />
|
|
|
|
<!-- Additional SEO -->
|
|
<meta name="robots" content="index, follow" />
|
|
<meta name="author" content="Vyla" />
|
|
|
|
<link rel="icon" href="/favicon.ico" />
|
|
<link rel="stylesheet" href="/assets/base.css" />
|
|
<link rel="stylesheet" href="/assets/highlight.css" />
|
|
<link rel="stylesheet" href="/assets/mintlify-overrides.css" />
|
|
|
|
<!-- JSON-LD Structured Data -->
|
|
<script type="application/ld+json">
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "SoftwareApplication",
|
|
"name": "Paths and playback events",
|
|
"description": "The complete Stream API playback contract, unified for movies and TV episodes.",
|
|
"url": "https://vyla.cc/stream-api/paths.html",
|
|
"applicationCategory": "MultimediaApplication",
|
|
"operatingSystem": "Windows, macOS, Linux, Android, Android TV",
|
|
"offers": {
|
|
"@type": "Offer",
|
|
"price": "0",
|
|
"priceCurrency": "USD"
|
|
}
|
|
}
|
|
</script>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div id="banner">
|
|
<span>Vyla is self-hosted. Run Vyla Home, embed the SDK, or deploy Stream API on infrastructure you control. Rights
|
|
holders can request source removal — <a href="/misc/dmca">DMCA policy</a>.</span>
|
|
<button id="banner-close" onclick="dismissBanner()" aria-label="Dismiss">✕</button>
|
|
</div>
|
|
|
|
<header id="navbar">
|
|
<div class="nav-top">
|
|
<a class="brand" href="/"><img src="/assets/images/logo.png" alt="Vyla" id="brand-logo" loading="lazy"
|
|
fetchpriority="low"></a>
|
|
<button id="search-trigger" type="button" onclick="openSearch()" aria-label="Search"></button>
|
|
<div class="links">
|
|
<button id="theme-toggle" type="button" onclick="toggleThemeMenu(event)" aria-label="Theme"></button>
|
|
</div>
|
|
</div>
|
|
<nav class="tabs">
|
|
<a class="tab-link" href="/">Vyla</a>
|
|
<a class="tab-link" href="/sdk">SDK</a>
|
|
<a class="tab-link active" href="/stream-api/overview">Stream API</a>
|
|
<a class="tab-link" href="/guides/integrations">Resources</a>
|
|
<a class="tab-link" href="/misc/credit">Misc</a>
|
|
</nav>
|
|
</header>
|
|
<div id="layout">
|
|
<nav id="sidebar">
|
|
<div class="group">
|
|
<p class="group-title">Overview</p>
|
|
<ul>
|
|
<li><a class="" href="/stream-api/overview">Overview</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="group">
|
|
<p class="group-title">Reference</p>
|
|
<ul>
|
|
<li><a class="active" href="/stream-api/paths">Paths</a></li>
|
|
<li><a class="" href="/stream-api/media-data">Media Data</a></li>
|
|
<li><a class="" href="/stream-api/operations">Operations</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="group">
|
|
<p class="group-title">Deployment</p>
|
|
<ul>
|
|
<li><a class="" href="/self-hosting">Self Hosting</a></li>
|
|
</ul>
|
|
</div>
|
|
</nav>
|
|
<div id="content-col">
|
|
<main class="prose">
|
|
<h1>Paths and playback events</h1>
|
|
<p class="page-description">The complete Stream API playback contract, unified for movies and TV episodes.</p>
|
|
<h2 id="playback-paths">Playback paths</h2>
|
|
<p>The API supports both the short paths below and <code>/api</code>-prefixed equivalents. A movie needs only
|
|
<code>id</code>; a TV episode also needs <code>season</code> and <code>episode</code>.
|
|
</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Media</th>
|
|
<th>Path</th>
|
|
<th>Response</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Movie</td>
|
|
<td><code>GET /movie?id=:id</code></td>
|
|
<td>Server-Sent Events</td>
|
|
</tr>
|
|
<tr>
|
|
<td>TV episode</td>
|
|
<td><code>GET /tv?id=:id&season=:season&episode=:episode</code></td>
|
|
<td>Server-Sent Events</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><code>id</code> is a TMDB ID. For example:</p>
|
|
<pre><code class="hljs language-bash">curl -N <span class="hljs-string">"http://localhost:7860/movie?id=155"</span>
|
|
curl -N <span class="hljs-string">"http://localhost:7860/tv?id=1396&season=1&episode=1"</span>
|
|
</code></pre>
|
|
<h2 id="event-contract">Event contract</h2>
|
|
<p>Playback routes use <code>text/event-stream</code>, not a single JSON document. Read each <code>data: </code>
|
|
line as JSON.</p>
|
|
<h3 id="meta"><code>meta</code></h3>
|
|
<p>Sent before source resolution completes. It can include TMDB metadata and an array of subtitle tracks.</p>
|
|
<pre><code class="hljs language-json"><span class="hljs-punctuation">{</span>
|
|
<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"meta"</span><span class="hljs-punctuation">,</span>
|
|
<span class="hljs-attr">"meta"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"id"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">155</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"title"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"The Dark Knight"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
|
<span class="hljs-attr">"subtitles"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-punctuation">{</span> <span class="hljs-attr">"label"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"English"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"file"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"https://…"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"vtt"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"source"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"v1"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">]</span>
|
|
<span class="hljs-punctuation">}</span>
|
|
</code></pre>
|
|
<h3 id="source"><code>source</code></h3>
|
|
<p>One event for each candidate that passes the service's verification pipeline.</p>
|
|
<pre><code class="hljs language-json"><span class="hljs-punctuation">{</span>
|
|
<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"source"</span><span class="hljs-punctuation">,</span>
|
|
<span class="hljs-attr">"source"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
|
|
<span class="hljs-attr">"source"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"provider-key"</span><span class="hljs-punctuation">,</span>
|
|
<span class="hljs-attr">"label"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Provider name"</span><span class="hljs-punctuation">,</span>
|
|
<span class="hljs-attr">"url"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"http://localhost:7860/api?url=…"</span>
|
|
<span class="hljs-punctuation">}</span>
|
|
<span class="hljs-punctuation">}</span>
|
|
</code></pre>
|
|
<p>The <code>url</code> is ready for a player. HLS sources may be wrapped by Vyla's proxy so manifest segments
|
|
and keys can be fetched with the appropriate upstream headers. Some configured sources bypass proxying. Do not
|
|
assume a filename extension alone determines playback behavior.</p>
|
|
<h3 id="done"><code>done</code></h3>
|
|
<p>Sent after the configured attempts are complete.</p>
|
|
<pre><code class="hljs language-json"><span class="hljs-punctuation">{</span> <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"done"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"total"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">3</span> <span class="hljs-punctuation">}</span>
|
|
</code></pre>
|
|
<p><code>total: 0</code> means no playable sources were produced for that request. The SSE connection itself can
|
|
still be successful.</p>
|
|
<h2 id="client-rules">Client rules</h2>
|
|
<ol>
|
|
<li>Start playback as soon as the first <code>source</code> arrives.</li>
|
|
<li>Queue every later source for manual switching or automatic fallback.</li>
|
|
<li>Attach subtitle tracks from <code>meta</code> without blocking playback.</li>
|
|
<li>Treat an empty result as a normal product state, not a malformed response.</li>
|
|
<li>Abort the request when the viewer leaves the page or chooses another title.</li>
|
|
</ol>
|
|
<p>The <a href="/guides/integrations">integration guide</a> contains a practical player pattern; <a
|
|
href="/guides/error-handling">error handling</a> covers fallback behavior.</p>
|
|
</main>
|
|
<aside id="toc">
|
|
<p class="toc-title">On this page</p>
|
|
<ul>
|
|
<li><a href="#playback-paths">Playback paths</a></li>
|
|
<li><a href="#event-contract">Event contract</a></li>
|
|
<li><a href="#client-rules">Client rules</a></li>
|
|
</ul>
|
|
</aside>
|
|
</div>
|
|
</div>
|
|
<footer id="site-footer"><a href="https://discord.gg/5eqRhKeywG" target="_blank" rel="noopener">Discord</a></footer>
|
|
<script src="/assets/app.js"></script>
|
|
</body>
|
|
|
|
</html> |