The Mato player is an embeddable audio player you can drop into any website. It supports four size variants, light and dark themes, accent color overrides, start-time deep links, chapter markers, and synchronized transcript highlighting. Mato also offers a show-level embed that plays a list of recent episodes.
This guide covers both embed dialogs, how to customize the player, and the URL parameters available for advanced control.
Open the episode embed dialog
Open a published episode's detail page inside your workspace. Click More actions (the ••• button) in the header, then select Embed player. The Embed Mato player dialog opens with a live preview alongside the generated code.
If an episode has not finished publishing yet, the menu still shows the option, labeled Embed available after publishing.
Choose a Player size and Theme, and optionally a Start at time (seconds, mm:ss, or hh:mm:ss), then click Copy code. The dialog also shows the public episode link with Copy link and Open buttons. The Theme dropdown offers Light and Dark; there is no Auto option in the dialog itself, though the underlying player supports it as described below.
Open the show embed dialog
To embed a scrollable list of episodes instead of one, go to All podcasts in the sidebar, open the menu on the show's card, and select Embed. The Embed show player dialog offers a Theme (Light or Dark) and an Episodes to show slider from 1 to 20.
Choose a player variant
The episode dialog's Player size has four options:
- Small (approx. 96px tall). Cover art, title, show name, play button, and a time counter. No waveform or transport controls. Good for sidebars, cards, or tight spaces.
- Compact (approx. 170px tall). Cover art and metadata on the left, waveform and transport controls on the right. Works well in blog post headers or narrow content columns.
- Standard (approx. 300px tall). Full-width layout with cover art, metadata, waveform, and playback controls stacked vertically. Includes a collapsible transcript panel. Best for dedicated episode pages.
- Medium (approx. 520px tall). Same as Standard, plus a chapter markers section with a visual timeline and a clickable chapter list. Also includes the transcript panel. Best when the episode has chapter data.
If you edit the copied snippet and set data-variant="auto" (or ?variant=auto on the iframe URL directly), the player measures its container width and picks the best layout automatically: below 300px it uses Small, below 500px Compact, below 700px Standard, and above 700px Medium. Auto is not one of the dropdown's four choices; it is only reachable by editing the attribute yourself.
Pick a theme
Light renders a warm off-white background with dark text. Dark renders a near-black background with light text.
If you set data-theme="auto" (or ?theme=auto) by hand in the copied snippet, the player follows the listener's preferred color scheme instead of a fixed choice. This is not offered as a dropdown option; you add it yourself.
Copy the embed code
The dialog's output is a script-tag embed, not a raw iframe. For an episode, it looks like this:
<div data-mato-player="EPISODE_IDENTIFIER" data-theme="light" data-variant="compact" data-start="600"></div> <script src="https://heymato.com/embed/player.js" async></script>
EPISODE_IDENTIFIER can be the episode ID from Mato's embed dialog or the episode <guid> exposed in the show's RSS feed.
The script discovers the data-mato-player div, creates an iframe, and manages auto-resizing so the player fits its content without scrollbars.
Customize with URL parameters
The embed iframe URL supports several query parameters for fine-grained control. These are appended to the player URL (/embed/player/EPISODE_IDENTIFIER). If you are using the script-tag embed, add the equivalent data-* attributes to the div instead.
Start time (?t=)
Jump to a specific timestamp when the player loads. The value can be seconds, mm:ss, or hh:mm:ss.
/embed/player/EPISODE_IDENTIFIER?t=10:00
This starts playback at the 10-minute mark. In a script-tag embed, add the same value as data-start="600" or data-start="10:00". Existing embeds that use data-t continue to work. Values above 86400 (24 hours) are capped.
Accent color (?accent=)
Override the default accent color with a six-character hex code (no # prefix). This is not exposed in either dialog; add it to the snippet by hand.
/embed/player/EPISODE_IDENTIFIER?accent=FF5500
In a script-tag embed, add the same value as data-accent="FF5500". The player uses this color for the play button highlight, active chapter indicator, active transcript line, and waveform progress. It also calculates a readable foreground color automatically so text on accent-colored surfaces stays legible.
Variant (?variant=) and theme (?theme=)
Set the layout directly in the URL or with data-variant: small, compact, standard, medium, or auto. Set the theme with ?theme= or data-theme: light, dark, or auto.
/embed/player/EPISODE_IDENTIFIER?variant=standard&theme=dark
Chapter markers
If the episode has chapter data, the Medium variant displays a chapter section below the waveform. It includes:
- A visual timeline bar with dots at each chapter boundary. Hover a dot to see the chapter title and timestamp.
- A scrollable chapter list. Each row shows the chapter title, timestamp, and a "Now" or "Go" label. Click any row to jump to that point.
The active chapter highlights as playback progresses. Chapters are only visible in the Medium variant; Small, Compact, and Standard skip the chapter section.
Transcript highlighting
When the episode has a transcript, the Standard and Medium variants include a collapsible Transcript panel. It works like this:
- Each transcript cue shows a timestamp on the left and the spoken text on the right.
- The currently active cue highlights and the panel auto-scrolls to keep it visible.
- Click any cue to jump playback to that point.
- If word-level timing data is available, individual words highlight as they are spoken. Click a specific word to seek to that exact moment.
Speaker labels appear as small badges above the cue text when the transcript includes speaker metadata. The transcript panel starts collapsed and opens when the listener clicks Show.
Show-level player
The show embed plays a list of the most recent published or distributed episodes, up to whatever count you chose in the dialog (default 10, maximum 20). Its script tag looks like this:
<div data-mato-show="your-show-slug" data-theme="light" data-limit="10" data-accent="FF5500"></div> <script src="https://heymato.com/embed/show.js" async></script>
data-limit controls how many episodes appear, and data-accent works the same way it does for the episode player; add it by hand if you want a custom color.
Visibility rules
Only episodes with a published or distributed status appear in the embed player. The episode's parent show must also be listed in the Mato directory or featured on the homepage. If these conditions are not met, the embed returns a 404.
Troubleshooting
The player shows "Audio is unavailable for this episode." The episode does not have a processed audio file yet. Check that audio generation completed on the episode detail page.
The iframe does not resize. Make sure you are using the script-tag embed, not a raw iframe. The script handles resizing automatically.
The embed returns a 404. Verify the episode is published and the show is publicly listed. Private or draft episodes are not accessible through embed URLs.