If you are building a custom player or embedding into an app, you should read these guidelines first.
Custom Apps and Players
Giving your audience a bespoke experience can boost your content's value and help you make the most out of your content. Whether it's an existing app or a new app that you are building, there are considerations that you must keep in mind when embedding Whooshkaa content and making playback available.
In addition to these, you should consult our guide on embedding content in a custom web player as most of those suggestions apply for your app too.
Guidelines and Suggestions
Use Your Feed
In general terms, the RSS feed that other apps use is the best source of content metadata for your player. While the Whooshkaa API may be a good place to go too, the RSS feed has already been a tried method in the industry for a long time and already has the public content and information that your listeners and viewers expect. In addition to this, the format is easy to consume and parse.
Download vs Stream vs Progressive Download
In general terms, episodes can be consumed by two means: they can be downloaded in one go, or progressively in byte chunks. When episodes are downloaded in one go, they are often referred to as a "download" and when they are downloaded in byte-range requests (chunks), they are often referred to as "streams" or "progressive downloads".
When a user requests a download, the request to the Whooshkaa Media Delivery Engine should be made without the Range header. When a user is not explicitly "downloading" the episode, the request should contain the byte range specified.
Do Not Proxy or Cache Episodes
Whooshkaa always serves dynamic content. This means that the content, the duration of the episode, the waveform, the cover art, transcripts and all other parts of the episode may be different for each listen. For this reason, it's important to not cache content and not proxy content through any servers in between.
Temporarily caching content on the user's device is fine and acceptable, especially if the user is looking to download the content for later listening or viewing.
Do Not Modify Episode (Enclosure) URLs
The URL of the episode must be used exactly as provided by Whooshkaa. This also means that in cases where it redirects to another location (e.g. a 302 redirect), you must not use the location to which it is redirected to as this may change in the future.
In addition, URLs may change through the life of the show, and so you should always refresh the URL provided from the feed.
Use the Episode GUID
Each Episode is uniquely identified using the GUID parameter from the feed. This is especially important as episodes can often have common titles, changed publish dates, varying descriptions, etc. All Whooshkaa Episodes have a GUID and it is important that you use it to identify episodes to update their metadata.
Do Not Automatically Download Episodes
Where possible, you should avoid downloading episodes on the user's behalf as this can unnecessarily consume the user's mobile data as well as give misleading listener data. All listens should be initiated by the user themselves.
Stop Auto-Downloads After 5 Episodes of Non-listens
If your app does do automatic downloads of episodes (e.g. for your users' convenience or downloads while on WiFi), you should stop after 5 episodes downloaded if the user has not yet listened to them.
Use a Custom User Agent
Most mobile OS players will use a standard, generic user agent to identify themselves. In order to give your app and identity in the Whooshkaa Insights, you should use a custom user-agent header. When you are able to work this well, let our support team know and we can activate a custom metric for your app in our Dashboard!
Talk to Us!
If you are building a custom app or integrating Whooshkaa into your existing app, we'd love to hear about it so that we can help you save time.