Play Documentation

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

Example:

<iframe
  src="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 Source 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 player menu if it differs from the uf feed URL.

Example

us=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 Source Embed Players

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

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:

ui=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
    src="...&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
    src="...&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
  src="https://play.prx.org/e?uf=https://example.com/rss/feed.xml"
  width="100%"
  height="200"
/>

Card Style RSS Player

Fixed Size

<iframe
  src="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
    src="https://play.prx.org/e?uf=https://example.com/rss/feed.xml&ca=1"
    style="position: absolute; inset: 0;"
  />
</div>

RSS Playlist

<iframe
  src="https://play.prx.org/e?uf=https://example.com/rss/feed.xml&sp=20"
  width="100%"
  height="600"
/>

Basic Audio File Player

<iframe
  src="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"
/>