> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/api-reference/web-player/custom-themes.md).

# Custom themes

Files, hosting rules, template syntax, values, and elements of a custom web player theme.

Use this reference when you replace the look of the Podigee web player with your own files. A custom theme uses a HyperText Markup Language (HTML) template, a Cascading Style Sheets (CSS) file, or both. You enter the addresses of the files in the web player settings. See [Configure the web player](https://docs.podigee.com/documentation/create-and-publish/publishing-and-distribution/configure-the-web-player).

* Podigee workspace: under **Design**, select **Your own CSS and HTML**. Enter the CSS address, and optionally the HTML address. Podigee saves new files as **External theme** on the new player. Without an HTML file, the player uses its own HTML with your CSS. Saved files that build on an older player come back on that player. To put new files on the new player, select **Standard** in **Theme to be overwritten** in the classic view.
* Classic view: use the fields below. Files that build on an older player can be changed only in the classic view. The Podigee workspace shows them in the row **Theme** with **Your own files**, and offers the switch to the new player.

## Before you start

* Your plan includes custom CSS or the external theme. The external theme is available on Creator and above, or an older plan that includes it. Custom CSS is available only on older accounts that include it. Current plans offer the external theme.
* You can host files on a server with HTTPS.
* You can maintain the theme yourself. The player script has no version number in its address. A player update applies to your theme at once.

## Choose the option

| Style in the web player settings | Files that you supply                      | What the player uses                                                                                                                                                                   |
| -------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Custom CSS**                   | One CSS file                               | The HTML of the theme that you select in **Theme to be overwritten**, with your CSS. Your CSS replaces the CSS of that theme. It does not add to it.                                   |
| **External theme**               | One CSS file, and optionally one HTML file | Your HTML and your CSS. Without an HTML file, the HTML of the base in **Theme to be overwritten**, with your CSS. In the Podigee workspace, this base is the new player for new files. |

After you select the style, the web player settings show the fields **CSS URI**, **HTML URI** (**External theme** only), and **Theme to be overwritten**. New custom styles use **Standard**. Existing custom styles keep their saved base, **Legacy** or **Standard (old version)**. Keep that base until you adapt the files for the new player. The player uses the panels of the selected base.

For both options, you can set one player height for your website and one for embeds. Use the field **Webplayer height (px)** in the sections **On website** and **Embedded**. The oEmbed response uses the height of the requested context. Without a context, it uses the height for embeds.

## Host the files

| File      | Rule                                                                                                                                                                              |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CSS file  | Serve it with HTTPS. The player loads it as a style sheet.                                                                                                                        |
| HTML file | Serve it with HTTPS. The player loads it with a script request from `https://player.podigee-cdn.net`. Send the header `Access-Control-Allow-Origin` with this origin or with `*`. |

## Write the template

Put the template into one HTML element. The player fills in values with the prefix `pp`:

| Syntax              | Result                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `{ title }`         | Inserts the value as text.                                                                               |
| `pp-src="coverUrl"` | Sets the attribute `src` to the value. The same works for other attributes, for example `pp-href="url"`. |
| `pp-if="url"`       | Shows the element only when the value is set.                                                            |
| `pp-unless="url"`   | Shows the element only when the value is not set.                                                        |

This template shows the minimum structure:

```html
<div class="podcast-player">
  <audio></audio>

  <div class="main-player">
    <img class="cover-image" pp-src="coverUrl" />

    <div class="controls">
      <button class="play-button"></button>
    </div>

    <div class="episode-basic-info">
      <div class="episode-title">
        <a pp-if="url" pp-href="url" target="_parent">{ title }</a>
        <span pp-unless="url">{ title }</span>
      </div>
      <div class="episode-subtitle">{ subtitle }</div>
    </div>

    <div class="controls-advanced">
      <button class="backward-button"></button>
      <button class="forward-button"></button>
      <button class="speed-toggle">1x</button>
    </div>

    <div class="buttons"></div>

    <progressbar></progressbar>
  </div>

  <div class="panels"></div>
</div>
```

## Elements that the player controls

| Element            | Function                                                                 |
| ------------------ | ------------------------------------------------------------------------ |
| `audio`            | The media element. The template must contain it.                         |
| `progressbar`      | The progress bar.                                                        |
| `.play-button`     | Starts and pauses the playback.                                          |
| `.backward-button` | Jumps back, 10 seconds by default.                                       |
| `.forward-button`  | Jumps forward, 30 seconds by default.                                    |
| `.speed-toggle`    | Changes the playback speed.                                              |
| `.cover-image`     | Shows the cover image.                                                   |
| `.buttons`         | Receives the buttons of the panels, for example chapter marks and share. |
| `.panels`          | Receives the panels.                                                     |

## Values in the template

| Value                             | Content                                                                                                                           |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `title`, `subtitle`               | The title and the subtitle of the episode.                                                                                        |
| `description`                     | The description of the episode, as HTML.                                                                                          |
| `coverUrl`                        | The address of the episode cover image. Without an episode cover, the podcast cover image. Without both, a Podigee default image. |
| `url`                             | The external URL of the episode, or the address of the episode page when the episode has no external URL.                         |
| `number`                          | The episode number.                                                                                                               |
| `duration`                        | The duration of the episode in seconds.                                                                                           |
| `podcastTitle`, `podcastSubtitle` | The title and the subtitle of the podcast.                                                                                        |
| `podcastUrl`                      | The address of the podcast website.                                                                                               |
| `showSubscribeBar`                | `true` when the subscribe bar is switched on.                                                                                     |
| `showPodigeeBranding`             | `true` when the player shows the Podigee logo.                                                                                    |
| `locale`                          | The language of the player, for example `en-US`.                                                                                  |
| `translations`                    | The player labels in the language of the player, for example `translations.playPause`.                                            |

## If the theme does not load

* The player shows no theme: open the HTML file address in a browser. Check that it loads with HTTPS and that the response contains the header `Access-Control-Allow-Origin`.
* The controls do not work: check that the template contains the `audio` element and the class names in the table above.

## Related pages

* [Embed codes and configuration URLs](https://docs.podigee.com/api-reference/web-player/embed-codes-and-configuration-urls.md)
* [Player JavaScript API](https://docs.podigee.com/api-reference/web-player/javascript-api.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.podigee.com/api-reference/web-player/custom-themes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
