wherever.audio

Information for Developers

Contents

Deep linking

This section documents the public URL routes that other applications can use to deep-link into wherever.audio. Both routes 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.)