=== Brainstorm Cafe Podcast Player ===
Contributors: brainstormcafe
Tags: podcast, podcast player, rss, audio, episodes
Requires at least: 6.3
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.4.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A polished RSS podcast player with themes, layouts, search, sticky controls, and Podcasting 2.0 support—free forever.

== Description ==

Brainstorm Cafe Podcast Player turns any public podcast RSS feed into a polished, searchable episode library for your WordPress website.

Add your feed once, choose the layout, theme, and details you want to show, then place the player with a block or shortcode. The plugin plays media from your existing podcast host; it does not require you to republish episodes in WordPress.

= Free forever—without catches =

Brainstorm Cafe Podcast Player is free and will always remain free. There is no premium edition, feature paywall, recurring subscription, license key, required account, or limited trial. New features and updates are available to everyone.

The plugin is open-source software released under GPLv2 or later, the same license family used by WordPress.

= Player and listening experience =

* One polished, full-width shared audio player with play, pause, seek, elapsed-time, volume, mute, and playback-speed controls.
* Optional compact sticky player that stays available after playback starts.
* Complete episode titles displayed above the full-width controls.
* Responsive layouts for phones, tablets, and desktops.
* Search, season filtering, and progressive "Show more" browsing.
* Expandable episode notes.
* Native browser audio controls as a no-JavaScript fallback.

= Themes, layouts, and visible details =

* Light and dark themes with matching search and filter controls.
* Optional transparent outer background for better site-theme integration.
* List, card, and compact episode layouts.
* Individual visibility controls for podcast artwork and description, episode artwork and notes, dates, duration, season and episode numbers, authors, links, and explicit-content labels.
* CSS custom properties and an in-dashboard CSS guide for safe visual customization.

= WordPress integration =

* A dedicated Podcast Player section in the WordPress dashboard.
* A dynamic Brainstorm Cafe Podcast Player block with per-block overrides.
* A flexible `[brainstorm_cafe_podcast_player]` shortcode with per-embed overrides.
* One site-wide feed plus an optional feed override for individual blocks or shortcodes.
* A saved-settings preview, one-hour normalized feed cache, and manual refresh control.
* Optional Apple Podcasts, Spotify, YouTube, RSS, and two administrator-defined links.

= Podcasting 2.0 =

* Transcript and caption links when supplied by the podcast feed.
* Chapter markers that listeners load on demand and can use to seek within an episode.

= Privacy-minded by default =

* No analytics, advertising, tracking pixels, external fonts, or third-party JavaScript.
* No Brainstorm Cafe account or hosted service is required.
* Feed retrieval is handled by WordPress, while audio and images continue to come from the publisher-selected hosts.

== Installation ==

1. Upload the `brainstorm-cafe-podcast-player` folder to `/wp-content/plugins/`, or install the ZIP through Plugins > Add New > Upload Plugin.
2. Activate Brainstorm Cafe Podcast Player.
3. Open Podcast Player in the main dashboard menu.
4. Enter the public RSS feed URL supplied by your podcast host, choose the player options, and save.
5. Insert the Brainstorm Cafe Podcast Player block or add `[brainstorm_cafe_podcast_player]` to a page.

== Block ==

Insert the **Brainstorm Cafe Podcast Player** block from the Embed category. The block uses the site-wide settings by default and provides inspector controls for:

* Feed URL
* Theme
* Layout
* Transparent background
* Sticky mode
* Episodes shown at once
* Total episodes available
* Search
* Season filtering
* Podcasting 2.0 transcripts
* Podcasting 2.0 chapters

Leave an override empty, or set its episode number to 0, to inherit the dashboard setting.

== Shortcode ==

The basic shortcode uses every saved setting:

`[brainstorm_cafe_podcast_player]`

Override the most common options for one embed:

`[brainstorm_cafe_podcast_player theme="dark" layout="cards" transparent="yes" sticky="yes" per_page="12" max_episodes="60"]`

Use another public feed for one embed:

`[brainstorm_cafe_podcast_player feed="https://example.com/podcast/feed.xml"]`

Available attributes:

* `feed`: Public HTTP or HTTPS RSS feed URL.
* `theme`: `light` or `dark`.
* `layout`: `list`, `cards`, or `compact`.
* `transparent`: `yes` or `no`.
* `sticky`: `yes` or `no`.
* `per_page`: Episodes revealed at once, from 1 to 50.
* `max_episodes`: Episodes loaded from the feed, from 1 to 200.
* `search`: `yes` or `no`.
* `season_filter`: `yes` or `no`.
* `podcast_image`: `yes` or `no`.
* `podcast_description`: `yes` or `no`.
* `episode_images`: `yes` or `no`.
* `episode_descriptions`: `yes` or `no`.
* `transcripts`: `yes` or `no`.
* `chapters`: `yes` or `no`.
* `dates`: `yes` or `no`.
* `duration`: `yes` or `no`.
* `numbers`: `yes` or `no`.
* `episode_links`: `yes` or `no`.
* `author`: `yes` or `no`.
* `explicit`: `yes` or `no`.
* `subscribe`: `yes` or `no`.

The legacy aliases `[simple_podcast_player]` and `[podcast_feed_player]` remain supported with the same attributes.

== CSS customization ==

Open Podcast Player > CSS guide for copyable examples and a selector reference. The neighboring Shortcode guide tab documents every shortcode attribute. A longer CSS guide is included at `docs/customizing-css.md` inside the plugin.

Add custom rules in Appearance > Customize > Additional CSS, a child theme, or the site editor. Do not edit the plugin files because updates replace them.

The main design tokens can be overridden in one place:

`.spp-player { --spp-accent: #c2410c; --spp-radius: 8px; --spp-font: Georgia, serif; }`

== Feed behavior ==

WordPress retrieves and caches the RSS feed. The plugin also caches its normalized episode data for one hour. Use **Refresh feed now** on the settings page after publishing an episode when an immediate refresh is needed.

The player supports standard RSS and Atom enclosures plus common iTunes podcast tags for artwork, duration, season, episode number, author, episode type, and explicit-content status. It also detects Podcasting 2.0 `podcast:transcript` and `podcast:chapters` episode tags. Missing optional data is simply omitted.

Chapter JSON is never downloaded during the initial page load. A listener first opens the Chapters panel and selects **Load chapters**. Supported chapter markers become buttons that seek the shared audio player to the chapter start time.

== External services ==

This plugin does not depend on a service operated by Brainstorm Cafe. It works with URLs supplied by the site administrator or declared by the podcast publisher:

* WordPress requests the administrator-configured podcast RSS URL to parse and cache the feed. The podcast host receives the website server's request data, such as its IP address and HTTP user agent.
* A visitor's browser requests podcast audio and images from the URLs declared in the RSS feed when those resources are displayed or played.
* When a visitor selects **Load chapters**, the browser requests the HTTPS chapter JSON URL declared by that episode's `podcast:chapters` tag. The chapter host receives the visitor's request, without cookies or a referrer from this plugin. The request may fail if the publisher has not enabled browser access to the chapter file.
* Transcript, episode, and listening-platform links take visitors to their configured destinations only when selected.

Those independently operated podcast and platform hosts have their own terms and privacy policies. Site administrators should review the policies of the feed and services they choose to display.

== Privacy ==

Brainstorm Cafe Podcast Player does not collect analytics or personal information and does not send usage data to Brainstorm Cafe. Search, season filtering, pagination, audio controls, and chapter navigation run in the visitor's browser.

== License ==

Copyright 2026 Matt Lawhead and Brainstorm Cafe.

Brainstorm Cafe Podcast Player is free software released under the GNU General Public License, version 2 or any later version. The complete GPLv2 text is included in `LICENSE.txt`.

== Uninstall behavior ==

Settings are preserved by default. To remove the plugin option and its cached feed data during uninstall, first enable **Delete settings when the plugin is uninstalled** under Data cleanup.

== Frequently Asked Questions ==

= Will this plugin remain free? =

Yes. Brainstorm Cafe Podcast Player is and will remain free, without a premium edition, feature paywall, subscription, license key, or required account. Updates and new features are available to everyone.

= Why does my newest episode not appear immediately? =

Feeds are cached for performance. Choose **Refresh feed now** under Podcast Player in the dashboard.

= Can I add more than one podcast? =

The settings screen stores one site-wide feed. A block or shortcode can override the feed URL for an individual embed.

= Does the player autoplay? =

No. Playback only starts after a visitor selects an episode.

= Does search send data anywhere? =

No. Search and season filtering happen locally in the visitor's browser against the episodes already on the page.

= What happens if an episode has no audio enclosure? =

The episode remains visible, but its action is labeled "Audio unavailable."

= Why do chapters ask me to load them? =

Podcasting 2.0 chapter files are hosted separately from the RSS feed. Loading them only after a listener chooses avoids hidden third-party requests and keeps the initial episode list fast. If browser access is unavailable, the original chapter file can still be opened directly.

== Changelog ==

= 1.4.3 =

* Renamed plugin-wide PHP constants to use the complete Brainstorm Cafe Podcast Player prefix required by WordPress Plugin Checker.

= 1.4.2 =

* Updated the Plugin URI to the dedicated Brainstorm Cafe podcast plugin page so it is distinct from the Author URI.

= 1.4.1 =

* Updated uninstall function and multisite variable prefixes to match the rebranded plugin slug and satisfy WordPress Plugin Checker naming rules.

= 1.4.0 =

* Rebranded the plugin as Brainstorm Cafe Podcast Player with the new `brainstorm-cafe-podcast-player` distribution slug and text domain.
* Added `[brainstorm_cafe_podcast_player]` as the recommended shortcode while preserving both existing shortcode aliases.
* Added a clear free-forever commitment with no paywalls, subscriptions, license keys, or required accounts.
* Expanded the WordPress.org description, feature overview, privacy notes, and documentation.

= 1.3.2 =

* Matched the search and season controls to the selected light or dark player theme.
* Protected browse controls from conflicting WordPress theme form styles.
* Replaced the font-dependent search character with a consistent SVG icon.

= 1.3.1 =

* Made the sticky player substantially shorter with a compact responsive layout.
* Kept sticky controls fully opaque when the transparent-background option is enabled.
* Replaced font-dependent play and pause characters with consistent SVG icons.
* Removed inherited underlines from player controls and episode utility links.

= 1.3.0 =

* Added Podcasting 2.0 transcript and on-demand chapter support.
* Added global, block, and shortcode visibility controls for transcripts and chapters.
* Updated the dynamic block to Block API version 3.
* Added the required languages directory and corrected uninstall global prefixes for Plugin Check.
* Added the complete GPLv2 license text and an explicit GPLv2-or-later grant.
* Fixed front-end browsing initialization when search and season filters are both hidden.

= 1.2.0 =

* Moved the settings screen to its own top-level Podcast Player dashboard menu.
* Added a Brainstorm Cafe credit panel above the settings.
* Added an in-dashboard Shortcode guide beside the CSS guide.
* Added transparent-background settings with block and shortcode overrides.

= 1.1.0 =

* Redesigned the shared player so the complete episode title spans the player width.
* Added integrated play, seek, time, volume, mute, and playback-speed controls.
* Retained native browser controls as a progressive-enhancement fallback.
* Improved responsive and sticky-player presentation.

= 1.0.0 =

* Initial release.
