documentation/stream-api/media-data/index.html

<!doctype html>
<html lang="en" class="dark">

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Subtitles and downloads — Vyla</title>
  <meta name="description" content="Unified media-data paths for movies and TV episodes." />
  <meta name="keywords"
    content="subtitles, downloads, media data, subtitle tracks, download links, VTT, SRT, subtitle API" />
  <link rel="canonical" href="https://vyla.cc/stream-api/media-data.html" />

  <!-- Open Graph / Facebook -->
  <meta property="og:type" content="website" />
  <meta property="og:url" content="https://vyla.cc/stream-api/media-data.html" />
  <meta property="og:title" content="Subtitles and downloads — Vyla" />
  <meta property="og:description" content="Unified media-data paths 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/media-data.html" />
  <meta property="twitter:title" content="Subtitles and downloads — Vyla" />
  <meta property="twitter:description" content="Unified media-data paths 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": "Subtitles and downloads",
    "description": "Unified media-data paths for movies and TV episodes.",
    "url": "https://vyla.cc/stream-api/media-data.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="" href="/stream-api/paths">Paths</a></li>
          <li><a class="active" 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>Subtitles and downloads</h1>
        <p class="page-description">Unified media-data paths for movies and TV episodes.</p>
        <h2 id="subtitle-paths">Subtitle paths</h2>
        <table>
          <thead>
            <tr>
              <th>Media</th>
              <th>Path</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>Movie</td>
              <td><code>GET /subtitles/movie/:id</code></td>
            </tr>
            <tr>
              <td>TV episode</td>
              <td><code>GET /subtitles/tv/:id/:season/:episode</code></td>
            </tr>
          </tbody>
        </table>
        <p>The same routes are available under <code>/api/subtitles</code>. A successful response is a JSON array of
          tracks; a missing result returns <code>404</code> with an error object.</p>
        <pre><code class="hljs language-json"><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://example.invalid/subtitles/en.vtt"</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>
</code></pre>
        <p><code>file</code> is the track URL, <code>type</code> is normally <code>vtt</code> or <code>srt</code>, and
          <code>source</code> identifies the subtitle backend. Prefer the tracks included in the playback
          <code>meta</code> event when you are already opening a playback stream; use these paths when subtitles are
          fetched separately.
        </p>
        <h2 id="download-paths">Download paths</h2>
        <table>
          <thead>
            <tr>
              <th>Media</th>
              <th>Path</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>Movie</td>
              <td><code>GET /downloads/movie/:id</code></td>
            </tr>
            <tr>
              <td>TV episode</td>
              <td><code>GET /downloads/tv/:id/:season/:episode</code></td>
            </tr>
          </tbody>
        </table>
        <p>The <code>/api/downloads</code> prefix is also supported. A successful response is an array; an empty array
          simply means no candidates were found.</p>
        <pre><code class="hljs language-json"><span class="hljs-punctuation">[</span>
  <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"url"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"https://example.invalid/file.mp4"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"quality"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1080p"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"size"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"2.14 GB"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"format"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"MP4"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">]</span>
</code></pre>
        <p>Download URLs are provider results, not durable Vyla-hosted files. Display quality and size as informational
          fields, and handle expired or unavailable links in your client.</p>
        <h2 id="request-and-response-rules">Request and response rules</h2>
        <ul>
          <li>IDs are TMDB IDs; TV paths additionally require season and episode numbers.</li>
          <li>Both families return JSON, unlike the SSE playback paths.</li>
          <li>Handle <code>404</code> for missing subtitles and <code>500</code> for an upstream or resolver failure.
          </li>
          <li>Do not block first playback on either call. Fetch them in parallel or after the player has started.</li>
        </ul>
      </main>
      <aside id="toc">
        <p class="toc-title">On this page</p>
        <ul>
          <li><a href="#subtitle-paths">Subtitle paths</a></li>
          <li><a href="#download-paths">Download paths</a></li>
          <li><a href="#request-and-response-rules">Request and response 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>