Add a player to your site

01Get a player ID

A player is the thing you embed. It points at a whole podcast or at specific episodes, and it has a public ID you paste into your HTML.

1. Open Account, then Audio players.
2. Create a player, name it for your own reference, and add what it should play: a whole podcast, one episode, or several episodes in the order you choose.
3. Copy the player ID.
4. Publish changes and keep the player enabled. Draft edits are not visible to your website visitors.

Open your audio players

The ID is meant to be public.It sits in your page source where anyone can read it, and that is fine. It grants one thing: permission to play the episodes you put in that player. It is not an API key, it reaches nothing else in your account, and deactivating the player revokes it everywhere at once.

New finished episodes in a whole-podcast player appear automatically. If you change the selected episodes or player settings, publish those changes. The embed code does not need replacing.

02Paste two lines

Replace YOUR_WIDGET_ID with your player ID. Put the script on your page and the div where the player should appear. In a website builder, use a custom HTML or embed block that allows scripts.

<script src="https://www.obbo.me/player/obboplayer.js" async></script>
<div data-obbo-player="YOUR_WIDGET_ID"></div>

That is a complete integration. The script finds every element with a data-obbo-player attribute and fills it in, whether the page has one player or ten. Loading the script twice is harmless.

Audio only downloads after someone presses play.The player loads its episode list and artwork with the page, but requests audio only after a visitor starts playback. A page view does not count as a play.

03Check your published page

Save and publish your website, then open the page as a visitor would. Some website editors do not run scripts inside their editing preview.

• Your podcast title and finished episodes should appear without signing in to Obbo.
• Press play, try the seek bar, and pause. Audio should only start after you ask for it.
• Check the page on a phone as well as a wider screen. If the player is missing, make sure your website editor allows custom HTML and external scripts.

You're ready.You can stop here. Explore the sections below only if you want another layout, your own branding, or a custom integration.

04Pick a layout

There are six visible layouts, plus auto. Choose one with data-obbo-ui. Omit it or use auto to follow your player's published compact or playlist setting.

Back to the player playground

<script src="https://www.obbo.me/player/obboplayer.js" async></script>
<div
  data-obbo-player="YOUR_WIDGET_ID"
  data-obbo-ui="list"
  data-obbo-theme="dark"
></div>

Every attribute

Several players on one page is fine.They share a single request for your episode list, and starting one pauses the others, so a visitor never ends up with two voices at once.

05Make it look like your site

The player renders into your page, not an iframe. Use the variables below to match your colors, corner radius and font. The example includes the class that connects your HTML to your CSS.

The quick way: nine variables

<div class="my-player" data-obbo-player="YOUR_WIDGET_ID"></div>

<style>
  .my-player {
    --obbo-player-accent: #a1482e;
    --obbo-player-radius: 8px;
    --obbo-player-font: system-ui, sans-serif;
  }
</style>

The thorough way: class names

Stable obbo- classes let your stylesheet target the controls. Prefer variables for branding; use classes for more detailed changes. The root's data-obbo-state attribute lets you style loading and error states. Keep error messages visible so visitors know when playback is unavailable.

.obbo-p[data-obbo-state="loading"] { opacity: 0.6; }
.obbo-p[data-obbo-state="error"] .obbo-note { font-weight: 700; }

If your CSS is aggressive, seal it off.Add data-obbo-isolate to an in-page layout to protect it from your site's CSS. The nine variables still pass through, but class-level styling no longer reaches inside. The dock layout attaches to the document and does not support shadow isolation.

06Build your own player

Skip the layouts entirely. createPlayer gives you episode data, playback and position; you write the markup. Listening still gets counted and expired audio links still recover, without either being your problem. The controls below are running the code underneath them.

<script src="https://www.obbo.me/player/obboplayer.js" async></script>

<button id="play" type="button" disabled>Play</button>
<span id="time">0:00</span>

<script>
  addEventListener('load', function () {
    var player = Obbo.createPlayer({ widgetId: 'YOUR_WIDGET_ID' });
    var button = document.getElementById('play');
    var time = document.getElementById('time');

    player.subscribe(function (state) {
      button.disabled = state.status !== 'ready' || !state.playable;
      button.textContent = state.playing ? 'Pause' : 'Play';
      time.textContent = Obbo.formatTime(state.position);
    });

    button.onclick = function () { player.toggle(); };
  });
</script>

Keep the button disabled until status is ready.On iOS, permission to play audio is tied to the tap that asked for it. A tap the player cannot act on yet is spent for nothing, and your visitor has to tap again.

07The follow-along transcript

The transcript layout puts the whole episode on your page as text, and keeps it in step with the audio. Every Obbo episode is transcribed with sentence-level timings as part of production, so there is nothing for you to prepare.

• The line being spoken is highlighted and scrolls itself into view. Scroll it yourself and it stops following, with a button to jump back — it will not fight you for the scrollbar.
• Clicking any line plays from there, which makes the episode quotable: a reader can find the sentence they want and hear it said.
• The transcript is selectable text that assistive technology can read once loaded. Keep essential written content in your page's own HTML when search visibility matters; JavaScript-rendered text is not guaranteed to be indexed.

<script src="https://www.obbo.me/player/obboplayer.js" async></script>
<div data-obbo-player="YOUR_WIDGET_ID" data-obbo-ui="transcript"></div>

Uses the transcript available for each episode.Finished transcripts are served by the embed API. If an episode has no transcript, playback still works and the player explains that no transcript is available. The playground includes a working read-along example.

08API reference

Obbo.createPlayer(options)

The player

The state

Also on Obbo

09React, Vue and friends

Do not rely on the automatic scan. A framework that re-renders the container will wipe out the player's markup and leave its event listeners behind. Mount it yourself and tear it down on unmount, into an element you never render into.

import { useEffect, useRef, useState } from 'react';

let sdkPromise;
function loadPlayer() {
  if (window.Obbo) return Promise.resolve(window.Obbo);
  if (sdkPromise) return sdkPromise;
  sdkPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = 'https://www.obbo.me/player/obboplayer.js';
    script.async = true;
    script.onload = () => {
      if (window.Obbo) resolve(window.Obbo);
      else {
        sdkPromise = null;
        script.remove();
        reject(new Error('Player SDK unavailable'));
      }
    };
    script.onerror = () => {
      sdkPromise = null;
      script.remove();
      reject(new Error('Player SDK could not load'));
    };
    document.head.appendChild(script);
  });
  return sdkPromise;
}

export function Player({ widgetId, locale = 'en' }) {
  const host = useRef(null);
  const [failed, setFailed] = useState(false);
  const [attempt, setAttempt] = useState(0);

  useEffect(() => {
    let cancelled = false;
    let cleanup;
    loadPlayer().then((Obbo) => {
      if (cancelled) return;
      const player = Obbo.createPlayer({ widgetId, locale, language: locale });
      const ui = Obbo.ui.list(host.current, player, { locale });
      cleanup = () => { ui.destroy(); player.destroy(); };
    }).catch((error) => {
      if (!cancelled) {
        console.error('Player failed to load', error);
        setFailed(true);
      }
    });
    return () => { cancelled = true; cleanup?.(); };
  }, [widgetId, locale, attempt]);

  return <>
    <div ref={host} />
    {failed && <p role="alert">
      The player could not load.
      <button type="button" onClick={() => {
        setFailed(false);
        setAttempt((value) => value + 1);
      }}>Try again</button>
    </p>}
  </>;
}

This example waits for the SDK, cancels late mounts, and destroys both the layout and player on cleanup. Pass your website's language as locale. Apply the same lifecycle to Vue's onMounted/onUnmounted or Svelte's onMount. Inline examples may need a CSP nonce or an external JavaScript file under your site's policy.

10Content-Security-Policy

If your site sends a Content-Security-Policy header, review these directives with your developer. Add the required hosts to your existing policy; these rows are not a complete policy to paste.

media-src is the one people miss.Audio is served from storage on a different host than the API. Leave it out and the player looks completely healthy, right up until someone presses play.

11What gets counted

Listening on your site shows up in your Obbo analytics: how many times the player loaded, how many plays started, and how much was actually heard.

• Your visitors are never identified. No account, no login, and the player sets no cookie. Reports are attributed to you as the owner, not to whoever is listening.
• A page view is not a play. Nothing counts as a play until audio actually starts.
• Listening time is measured rather than assumed. Skipping ahead does not count as having heard what you skipped.

12When it does not work

Still stuck?Send us the page address, your player ID and the value of Obbo.version at hello@obbo.me