How to customize the embeddable player

Play is a customizable audio embed player provided by PRX. It can play audio found in an RSS feed or a single audio file, and can be customized to fit your brand or site theme.

Getting Started

To get started, use either a public RSS feed URL in the `uf` parameter, or an audio file URL in the `ua` parameter. 

Base Embed URL: https://play.prx.org/e

Iframe Example:

`<iframe

href=”https://play.prx.org/e?uf=https://example.com/rss/feed.xml” 

width=”100%”

height=”200”

/>`

Note: Minimum height of your iframe should be 200px.

That is all you need to add the player to your page. 

Configuration Parameters

When setting up your embed, choose which set of configuration parameters you want to use, and add them to the base embed URL path in an `<iframe>` element in your content. The embed URL supports the following query parameters. 

RSS Feed Sourced Embed Parameters

uf

Must be a complete URL to a valid RSS feed. Feed items must include `<enclosure>` elements containing links to the audio files to play. By default, the player will display information for, and play the audio for the first item in the feed. If your feed is a list of podcast episodes, and the items are in reverse order (newer episodes first) the embed will act as a latest episode player.

Example: `uf=https://example.com/rss/feed.xml`

us (Optional)

Provide an alternate subscription RSS feed URL to use in the pulayer menu if it differs from the `uf` feed URL.

Example: `uf=https://example.com/rss/subscribe-feed.xml`

ge (Optional)

RSS item `<guid>` value. Selects which episode in the feed to initially use in the player. Keep in mind that if your feed has a capped length, ie. contains the latest 10 episodes, eventually the targeted guid could no longer be in the feed. When this happens, the player will fallback to playing the first item in the feed. To avoid this behavior, ensure you provide an uncapped feed URL in the `uf` parameter.

Example: `ge=0123456789abcdef`

sp (Optional)

Shows a playlist of items in the feed. Value should be the number of items to show in the playlist, or `all` to show all items in the feed. Requires `uf` parameter.

Be sure to change your embed’s `<iframe>` height to 600px or more to ensure playlist items are visible.

Examples: 

  • `sp=10`
  • `sp=25`
  • `sp=all`

se (Optional)

Filter feed items to a specific season. Requires `uf` and `sp` parameters.

Example: `se=2`

ct (Optional)

Filter feed items to a specific category. Requires `uf` and `sp` parameters.

Example: `ct=entertainment`

Audio File Sourced Embed Parameters

ua

File to play in the embed. Must be a complete URL to an audio file. When used with the `uf` parameter, this file will play instead of the audio of the RSS item. Has no effect when used with `sp` parameter.

Example: `ua=https://example.com/files/audio.mp3`

tt

Title to display in player.

Example: `tt=My+Audio+Title`

ts

Subtitle to display in player.

Example: `ts=Something+About+The+Audio`

ue (Optional)

Thumbnail image URL. Must be a complete URL to an image file.

Example: `ue=https://example.com/files/thumbnail.jpg`

Customization Parameters

These parameters are supported by both the RSS Feed and Audio File embed players. All parameters are optional.

ui

Custom background image URL used in player. Must be a complete URL to an image file.

Example: `ue=https://example.com/files/background.jpg`

ca

Enables a card style player, with a large thumbnail image above player controls.

Be sure to wrap the embed `<iframe>` with a responsive wrapper `<div>` if you need the embed to scale responsively.

Responsive Card Wrapper Example:

`

<div style=”width: 100%; height: calc(100% + 200px); position: relative;”>

<iframe href=”...&ca=1” style=”position: absolute; inset: 0;” />

</div>

`

When used with the `sp` parameter, increase the added pixel height of the wrapper to 800px or more.

Responsive Card Wrapper With Playlist Example:

`

<div style=”width: 100%; height: calc(100% + 800px); position: relative;”>

<iframe href=”...&ca=1” style=”position: absolute; inset: 0;” />

</div>

`

ac

Customize the accent color used in the player. Value must be a six or eight character hex color string. Do NOT include the `#` prefix.

Example: 

  • Correct: `ac=c3e5f1`
  • Incorrect: `ac=#c3e5f1`

Providing multiple `ac` parameters will result in your accent colors used in a gradient. Add as many colors as you need. Want a rainbow progress bar? You can do that. Elements that don’t support a gradient will use the first accent color.

Gradient Examples: 

  • `ac=c3e5f1&ac=fe42a3&ac=e3d819`

Gradient colors are distributed evenly by default. Add a percentage to the hex color to set a start position of that color.

Gradient With Positioned Colors Examples: 

  • `ac=CF3350&ac=CF3350+45%&ac=E7F5E0+55%&ac=E7F5E0`

th

Choose the color theme of the player. Value can be:

  • `dark` (default)
  • `light`
  • `auto` - Use the system color scheme of the user.

Embed Examples

Basic RSS Player

`<iframe

href=”https://play.prx.org/e?uf=https://example.com/rss/feed.xml” 

width=”100%”

height=”200”

/>`

Card Style RSS Player

Fixed Size

`<iframe

href=”https://play.prx.org/e?uf=https://example.com/rss/feed.xml&ca=1” 

width=”500”

height=”700”

/>`

Responsive

`<div style=”width: 100%; height: calc(100% + 200px); position: relative;”>

<iframe

href=”https://play.prx.org/e?uf=https://example.com/rss/feed.xml&ca=1”

style=”position: absolute; inset: 0;”

/>

</div>

`

RSS Playlist

`<iframe

href=”https://play.prx.org/e?uf=https://example.com/rss/feed.xml&sp=20” 

width=”100%”

height=”600”

/>`

Basic Audio File Player

`<iframe

href=”https://play.prx.org/e?ua=https://example.com/files/audio.mp3&tt=My+Audio&ts+Something+about+the+audio%ue=https://example.com/files/thumbnail.jpg&ui=https://example.com/files/background.jpg” 

width=”100%”

height=”200”

/>`

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request