Podlove Subscribe Button

This is a technical description of the Podlove Subscribe Button for developers and integrators. If you just want to use the button on your website, go to our Podlove Subscribe Button landing page.
TRY ME! – This button demonstrates it’s functionality by subscribing you to our test feed with your favorite podcast app.

The Podlove Subscribe Button is a simple web widget that every web site can use to make it super easy for users to launch an app or podcast cloud service and to pass the right URL to without having to touch the URL itself. The button automatically checks the OS used and has a builtin podcast client database with the clients’ capabilities and methods how to pass feed information into it. This database is constantly updated when new clients show up or existing ones receive new functionality.

Caution: The Podlove Subscribe Button currently only supports Audio podcasts and there are still some issues regarding web sites who deliver their content via https only. We are working on this and will present solutions in the near future.


Depending on your publishing environment, you have various options to easily integrate the Podlove Subscribe Button

  • If you are using the Podlove Publisher to publish your podcast with WordPress, all you need to do is to put the “Podcast Subscribe Button” widget in your sidebar or insert the button wherever you feel like using the [podlove-podcast-subscribe-button] shortcode. Done.
  • If you are using WordPress but not the Podlove Publisher yet (or you don’t have a podcast at all but just want to provide subcription options to your users), you can install the Podlove Subscribe Button plugin for WordPress. Create buttons by collecting corresponding metadata about your podcast and display it with either the “Podlove Subscribe Button” WordPress Widget or the WordPress Shortcode [podlove-subscribe-button]
  • To make the button show up on any website, turn to the embedding instructions in the Subscribe Button’s README document for all the options. Basically you just need to add a few lines of code into your HTML document and you’re set. Using this method you can also customize the appearance of the button (like colors) too.

To make things easy, we maintain a always-up-to-date version of the Podlove Subscribe Button on our own CDN so that you can automatically benefit from code fixes, new podcast clients and capabilities added to the database, visual updates and more. So we highly recommend including the button directly from our CDN as described in the README.

However, being a truly open source project, you can just take the code and host it on your own web site if you prefer (although this means you must take care of updates yourself which might not be what you want).


If you want to know more about how the button works or if you are developing a podcast app or service yourself, here is some background on how and why the button is designed the way it is.

Subscribing to a podcast is a simple process if you look at it from a technical perspective: a program (client) regularly loads a RSS feed document via a specific URL and checks for new entries.

But from a user perspective, this process is confusing at best and many times a roadblock to get people up and running receiving new episode from a podcast publisher on his/her specific device.

  • The concept of a “podcast feed” seems alien to some for a start
  • Identifying a feed or selecting a compatible one from a list
  • “Copying a Feed URL” is something many people don’t know how to do
  • Finding the right place in an podcast client to “paste” this URL into differs from app to app

The iTunes solution

In 2005, iTunes 4.7 has addressed these problems using two approaches at the same time. First, Apple integrated the Podcast Directory in the program so that subscribing to a podcast is just a click away. However, this only works within iTunes and with this particular  directory and not with other podcast clients and podcast web sites with a standard browser.

The second approach iTunes used was registering a so-called “URI scheme” with the operating system so that links in web pages that use “pcast:” or “itpc:” at the beginning of a link would automatically launch iTunes and pass the appended podcast feed URL to the program.

Following in iTunes’ footsteps, many podcast clients have also started to support the “pcast:” URI scheme trying to catch the same fish. But only a few operating systems (i.e. Android, Windows Phone 8 and  Windows 8) are capable of dealing with multiple apps trying to react the same URL, so once this link is fired, it is mostly undetermined, which app will get launched (or any at all).

However, many podcast clients have started registering their own URI Scheme for reacting to subscription requests. But in order to make use of this, web sites would have to know about all available podcast clients for a particular platform and then choose a proper URI scheme to activate them. This is where Podlove comes in for help.

The Podlove Solution

The Podlove Subscribe Button is a centrally hosted button for the web. You can choose from a variety of designs to match your web site’s needs and place it where ever you want. Once the button gets fed with the necessary information about the podcast, it takes over from there once the user clicks the button.

As mentioned above, the button maintains its own growing database of available podcast clients for almost every platform in use today. The button checks which operating system the browser is running on and does a lookup which clients might apply. Now the user can choose his/her favorite client and button then calls the proper URL to automatically launch the client and make it subscribe to the feed (either automatically or by providing another dialogue depending on the client).

Future upgrades to the button will allow fine-tuning of the subscription process by selecting a specific format (like AAC, MP3, Vorbis, Opus), variety (Audio, Video) and quality (High, Medium, Low) depending on what is actually offered by the web site. However, the button always tries to make an educated guess on which feed will the “best” to subscribe to so that these options can be totally ignored by users who either don’t care or simple don’t know what to select from these options.


The Podlove Subscribe Button is optimized for both mobile and desktop environments and tries to make use of the available screen spaces as good as possible. Right now, we explicitly support and test for these operating systems:

  • OS X
  • iOS
  • Android
  • Windows 8
  • Windows Phone 8
  • Linux, FreeBSD and other unixoid systems

We plan to add more operating systems soon as we go along and learn more about the behavior of particular systems and podcast clients.

But in addition to native apps, we also support podcast syncing backends or podcast clients on the web too. These cloud-based systems are becoming more and more popular as they allow both playback on the web as well as subscribing on one computer and syncing the subscription list to mobile devices.


As all our tools, the Podlove Subscribe Button is open source and free software. The code is on GitHub and we welcome your bug reports, pull requests and other suggestions. We invite podcast client developers to give feedback on the behaviour on the button to help us support more systems and apps.

If you develop a podcast client app (either native apps for computers or a web-based solution), here is a guide how to best integrate with the Podlove Subscribe Button. If you follow our recommendations, adding your app or cloud service is just a matter of adding a line of data to our code (and, to make it look nice, your app’s or service’s icon).

Feed URL Notation

Automatisation of the subscription process means passing around podcast feed URLs to the app or cloud service. To do that properly, it is very important to understand how feed URLs are actually notated when placed inside another URI or URL.

In the following documentation we will use <feed-url> as a placeholder for the podcast feed that is passed along by the Subscribe Button. Please note that you SHOULD be able to accept <feed-url> ALL of the following forms to be as compatible as possible:

http-URLs can be stated with or without the http:// part. All applications MUST support at least the version without http://.

  • example.com/feed/podcast/
  • http://example.com/feed/podcast/

In addition to that, please be aware that podcast feeds are not always accessible via http (only). https podcast feeds might not be very common today but they do exist and might proliferate in the future. So make sure you can deal with https feeds from the beginning as well:

  • https://example.com/feed/podcast/

While at it, make sure you can deal with podcast feeds that use IPv4 or IPv6 addresses instead of domain names. This might be uncommon for some podcasts but could be used for testing or temporary systems.

  • http://[2001:db8:::dead:beef:2342]/feed/podcast/

And to be complete, please be aware that some podcast feeds even might include authentication information. It depends on your app or service if you can or want to support protected feeds, but if you do, make sure you get it right from the start and if you don’t, you should at least detect the presence of that information and tell the user that you can’t handle it properly (especially do NOT send a request to the network in the first place). Also note that there might be either both a username and password or just a username information.

  • https://audience23:p4ssw0rd@example.com/feed/podcast/
  • https://listener2342@example.com/feed/podcast/

So now that you got your feed syntax right, let’s see how to actually register for getting subscription information.

App Integration

To connect your app to the Podlove Subscribe Button, your app MUST register at least one URI scheme to be opened via the Web Browser but you SHOULD register two: a common and an app-specific one.

On Android, you can alternatively also register to respond to a certain URL that is associated with your app and be activated this way but we recommend using a URI scheme nevertheless.

Common URI scheme

The first URI scheme the app should register is called pcast. We consider pcast to be the common URI scheme that is used to issue a “default” call to a podcast app on any given system.

On some systems, like Android, Windows 8 and Windows Phone 8, the system can automatically select an app if there is only one that can handle a certain URI scheme and presents a list of options if there is more than one. This is the best scenario for issuing a call to a “default podcast app”.

On OS X, certain podcast apps register pcast including iTunes. The user can also configure manually (using third party tools) which app should respond to that URI scheme.

On iOS the pcast scheme is reserved for the systems default podcast application. Try to register it anyway as it doesn’t hurt and maybe it might come in handy in the future.

So your app SHOULD be able to respond to URIs in ALL of the following forms. They MUST support at least the first version (with //)

  • pcast://<feed-url> (MUST)
  • pcast:<feed-url> (SHOULD)

App-specific URI scheme

In addition to the common URI scheme mentioned above we highly recommend registering an app-specific URI scheme too. On iOS, this is the ONLY way to make the Podlove Subscribe Button work with an app. We don’t care which scheme you use as long as your not squatting some other app’s internal scheme (really bad idea). And we don’t care what exact syntax you use as long as you deal properly with all the formats of the actual podcast feed as described above.

We have seen many different styles of subscription URIs, but we strongly encourage you to use the first of these examples (including a protocol and a path prefix before the feed URL) as this seems to be the most compatible way in the light of recent changes to popular web frameworks (we are looking at you, WebKit).

  • myapp://subscribe/<feed-url> (RECOMMENDED)
  • myapp://<feed-url>
  • myapp://x-callback-url/add?url=<feed-url>

As long as you choose a unique URI scheme AND you accept ALL of the different notations of a podcast feed, your podcast client is compatible with the Podlove Subscribe Button.

Cloud Integration

If you have a web-based podcast client or podcast syncing backend you might want to provide a URL syntax that allows the Podlove Subscribe Button to pass on a podcast feed for a user of your system to subscribe to. Once you receive this kind of request, make sure the user can properly login to your system (if not already logged in) and is then forwarded to a page that presents a dialog to confirm subscription to the feed.

As with Apps, make sure your URL accepts all possible podcast feed notations. Here are some examples of how your URL could look like:

  • https://example.com/podcast-cloud/subscribe/<feed-url>
  • https://example.com/podcast-cloud/subscribe?url=<feed-url>
  • https://example.com/podcast-cloud/?subscribe=<feed-url>

How to submit your app/service

If you want your app or service be listed within the Podlove Subscribe Button, make sure your app or service conforms to all of the rules stated above. Then submit your request by creating a new GitHub issue on our repository and list all of the following information:

  • Name of developer
  • Contact information of developer
  • Name of app or cloud service
  • Operating System (for apps)
  • Syntax of app-specific URI for podcast subscription
  • List of supported common URI schemes
  • High-quality image file of the icon for the app/service

If you have multiple apps or services please create one separate issue for each of them even if they all related to the same branding or service.

We will test the integration and when it works the way it should and your offering can be considered a good citizen of the overall podcasting infrastructure, we will add your app/service to our list.

Making the button available in many languages

We are starting with a few languages but want to translate the button into as many languages as possible. If you want to help and contribute translated strings, please proceed to translate.podlove.org.

20 thoughts on “Podlove Subscribe Button

  1. used the button at the user’s end. missed a thing to click and say: “IT WORKED!!” :) would be a nice alternative to just to have to close that overlay-popup, and probably it gives you a nice feedback, since I guess you cannot track a success with certainty.

  2. How can I add a new language on translate.podlove.org? I signed in via github but I can only contribute to existing translations. I’d like to contribute Esperanto, language code: eo.

  3. About my implementation experience using Squaresapce.

    The GitHub page is an okay resource. I saw hat the Podlove CDN option is the way to go, and realized that I’d need to put the code snippet some place on my page, so far so good.

    It isn’t totally clear that CDN and self-hosted are alternatives to each other and that what is written in the “Podcast data API-section” necessary for both of them (three times the same heading level, just put beneath each other). I say this as a nerd and I now know how it works and it is logical and all.
    But in the CDN section is already talked about *options* that need to be set. Only a closer look at the example code in the Podcast API section reveals that this is is the place where the *real* podcast information lives, feed address etc.

    The biggest problem is that there is not the slightest hint of where this data needs to be put. I host my podcast on a squarespace site, and I tried putting it next to the button info, but that didn’t work and I simply didn’t know what to do. I tried twice, googled for stuff, and was frustrated.
    I don’t expect a squarespace-specific manual, but some hint would’ve helped me a lot.

    Because: Only when I implemented the fb like button a few days later, I learned about the ‘Code Injection’ option in squarespace (squarespace manual for the fb button) and tried putting the Podlove button data beneath it, and that worked.
    Some info that the data needs to be put near the header or something like that would’ve been enough I think. I just thought ‘javascript stuff’ and had no idea, even thought it’d be a technical limitation of my site and the button just couldn’t work.

    Speaking of the fb like button: there is a great fb developer page where one can generate the button code, with different display options, the url you want to generate for etc. I don’t know how much effort a site like that is, but a playground like that would be great for the Podlove button, especially for the colors (I think there’s a mixup in the order of the colors in the github readme, but I am not sure).

    At one point, the readme says ‘There are currently three options you can set’ and after that there’s a code block with 6 lines in it. That’s confusing.
    Overall, the options that can be set could be presented more carefully, it takes a fair bit of superficial code-understanding and trial and error to figure things out. That’s where that playground would come in handy again.

    That’s it, I think. Cheers for a great project!

  4. Eine Frage, vielleicht bin ich da zu vorsichtig, aber mal besser Nachfragen wie das ist. Die Mini-Logos der verschiedenen Apps dürfen hier so einfach eingebaut sein/werden?
    Nicht das man dann Ärger mit den Herstellern der Apps bekommt, wenn man es auf der Seite hat?

  5. Hi, I want to translate the podcast subscribe button to Portuguese (Brazilian Portuguese), so I joined OneSky, but how may I add a new language?
    PS: Congratulations, you guys do such a great work!

  6. Pingback: Podlove Subscribe Button: The Redesign | Podlove

  7. Pingback: MT#090 – Say what again! – FROHE PFINGSTEN – MAKING TRACKS

  8. Pingback: German Public Radio adopts Podlove Subscribe Button | Podlove

  9. Pingback: Laberpodcast 10 – Podcastempfehlungen bei Spiegel Online – Ohren-Nahrung

  10. Pingback: Podcast-Analyse: 97,5% Webplayer vs. 2,5% Abonnierer – Chris Marquardt's Soapbox

  11. Vorerst 1000 Dank für den Subscribebutton, welch ein Segen dort wo er auftaucht :)
    Mir ist aufgefallen, dass er bzgl. Castro nicht ganz aktuell ist. Er zeigt noch das alte Logo von “Castro 1” an, leitet aber an “Castro 2” weiter. Man könnte natürlich Castro 2 seperat hinzufügen oder das Logo ändern und Support für Castro 1 droppen bzw. wenn möglich nur als fallback an Castro 1 weiterleiten.

  12. Absolument incompréhensible pour modifier les champs FM PLAYER et les autres plateformes ? Pourquoi ne pas avoir conçu une IHM pour ça ?!

    Application fait par des développeurs pour des développeurs, les autres passez vite votre chemin !

  13. Pingback: Interne Verlinkung & Informationsarchitektur - SEOHouse 73 Podcast

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.