wherever.audio

Information for Developers

Contents

Deep linking

You are welcome to link to wherever.audio from your site or app. A plain link to https://wherever.audio opens the player. The two routes below go straight to a show or an episode. Both live under the https://wherever.audio origin and accept their parameters as standard URL query string values.

When you build a link, remember to URL-encode the values — RSS feed URLs in particular contain : and / characters that must be percent-encoded.

Linking to a show: /show

The /show route opens the show page for a single podcast.

Parameters

Name Required Description
rssUrl Yes The podcast’s RSS feed URL.
feedGuid No The channel-level Podcasting 2.0 <podcast:guid> value. Used as a fallback: if the rssUrl fails to load, the player attempts to resolve the feedGuid to a new rssUrl and reload.

Example

https://wherever.audio/show?rssUrl=https%3A%2F%2Fmarquee.wherever.audio%2Fabout-wherever%2Frss.xml

Linking to an episode or clip: /listen

The /listen route opens the playback page. It is also the route used by wherever.audio’s own share links, so the parameters it accepts cover both simple “play this episode” links and richer “play this clip starting here” links.

If rssUrl is provided without an itemGuid, the player will load the feed and resume whatever the user was last listening to from that feed (if any).

Parameters

Name Required Description
rssUrl Yes The podcast’s RSS feed URL.
itemGuid No The episode’s <guid> value. Required to deep-link to a specific episode rather than the feed’s most recent or last-played episode.
feedGuid No The channel-level Podcasting 2.0 <podcast:guid> value. Used as a fallback: if the rssUrl fails to load, the player attempts to resolve the feedGuid to a new rssUrl and reload.
t No Start time in seconds (decimal allowed). Playback begins at this offset.
e No Clip end time in seconds (decimal allowed). When playback passes this offset, the clip ends. Use together with t to share a specific clip range.
fallbackLink No A URL the player can fall back to when an episode’s own <link> is missing. Typically the episode’s web page on the publisher’s site.

Example — episode link

https://wherever.audio/listen
  ?rssUrl=https%3A%2F%2Fexample.com%2Ffeed.xml
  &itemGuid=episode-123
  &feedGuid=917393e3-1b1e-5cef-ace4-edaa54e1f810

Example — clip link

https://wherever.audio/listen
  ?rssUrl=https%3A%2F%2Fexample.com%2Ffeed.xml
  &itemGuid=episode-123
  &feedGuid=917393e3-1b1e-5cef-ace4-edaa54e1f810
  &t=312.5
  &e=348.0

(Whitespace in the examples above is for readability — real links must be on a single line with no whitespace.)

Wherever logo

Use the logo alongside a link to wherever.audio, or a deep link from the section above, to show that content can be played in Wherever.

Files

The logo is square with a solid orange background. Use the SVG wherever you can; the PNGs are renders of the same file for places that need a bitmap.

File Format Size
wherever-logo.svg SVG any
wherever-logo-1024.png PNG 1024 × 1024
wherever-logo-512.png PNG 512 × 512
wherever-logo-256.png PNG 256 × 256
wherever-logo-128.png PNG 128 × 128
wherever-logo-64.png PNG 64 × 64
wherever-logo-32.png PNG 32 × 32

All files live under https://docs.wherever.audio/logo/. Hosting your own copy is fine, and preferred for anything high-traffic.

Example — “Listen in Wherever” link

<a
  href="https://wherever.audio/show?rssUrl=https%3A%2F%2Fexample.com%2Ffeed.xml"
>
  <img
    src="https://docs.wherever.audio/logo/wherever-logo.svg"
    alt="Listen in Wherever"
    width="48"
    height="48"
  />
</a>

Usage guidelines

Questions about logo use: [email protected].