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.

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.

Adding an episode later makes it appear in every embed of that player straight away. Nothing needs re-pasting.

02Paste two lines

Put the script anywhere on the page, and the div where you want the player.

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

<div data-obbo-player="YOUR_PLAYER_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.

Nothing downloads until someone presses play.The player fetches its episode list on load, but no audio is requested until a visitor actually starts one. Putting a player on a page costs your visitors nothing and never registers a play that did not happen.

03Pick a layout

Seven are built in. Choose one with data-obbo-ui; leave it off and you get whichever you selected when you made the player, so you can change your mind later without editing any pages.

<div data-obbo-player="YOUR_PLAYER_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.

04Make it look like your site

The player renders into your page's own DOM, not a sealed frame. Your stylesheet reaches it and your fonts are inherited.

The quick way: nine variables

.my-player {
  --obbo-player-accent: #e5484d;
  --obbo-player-radius: 4px;
  --obbo-player-font: 'Söhne', system-ui, sans-serif;
}

@media (prefers-color-scheme: dark) {
  .my-player {
    --obbo-player-bg: #181d24;
    --obbo-player-fg: #f2f5f8;
  }
}

The thorough way: class names

Every element carries a stable obbo- class, and every rule we ship is a single class selector, so your own rule wins without needing !important. The root also carries data-obbo-state, which lets you style the loading and error phases without reading our internals.

.obbo-p[data-obbo-state="loading"] { opacity: 0.6; }
.obbo-p[data-obbo-state="error"]   { display: none; }

If your CSS is aggressive, seal it off.A heavy framework reset can reach into the player. Add data-obbo-isolate and it renders in a shadow root instead: immune to your stylesheet, though the nine variables still pass through, so you keep the colour controls and lose only the class-level ones.

05Build 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.

<button id="play" disabled>Play</button>
<span id="title"></span>
<div id="track"><div id="fill"></div></div>

<script>
  var player = Obbo.createPlayer({ widgetId: 'YOUR_PLAYER_ID' });

  player.subscribe(function (state) {
    play.disabled     = state.status !== 'ready';
    play.textContent  = state.playing ? 'Pause' : 'Play';
    title.textContent = state.episode ? state.episode.title : '';
    fill.style.width  = (state.position / state.duration * 100) + '%';
  });

  play.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.

06The 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 text is real text in your page, so search engines index it and screen readers read it. An episode that would otherwise be an opaque audio box becomes content about your subject.

<div data-obbo-player="YOUR_PLAYER_ID"
     data-obbo-ui="transcript"></div>

Not switched on yet.Transcripts are produced for every episode but are not yet published on the embed API, so this layout currently shows the player with a note in place of the text. It will fill in on its own once we turn the field on — nothing on your page needs to change.

07API reference

Obbo.createPlayer(options)

The player

The state

Also on Obbo

08React, 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.

function Player({ widgetId }) {
  const host = useRef(null);

  useEffect(() => {
    const player = Obbo.createPlayer({ widgetId });
    const ui = Obbo.ui.list(host.current, player);
    return () => { ui.destroy(); player.destroy(); };
  }, [widgetId]);

  return <div ref={host} />;
}

Load the script once, in your document head or through a small loader, before the effect runs. The same applies to Vue's onMounted and onUnmounted, and to Svelte's onMount.

09Content-Security-Policy

If your site sends a Content-Security-Policy header, it needs three directives.

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.

10What 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.

11When it does not work

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