# MediaBlaster Documentation — Full Context

Generated from the current files in content/docs. MediaBlaster uses WordPress as the media backend and connects that content to app templates. The Roku Launch Kit is the only app template currently available.

Documentation index: https://www.mediablaster.io/docs

## App Config

URL: https://www.mediablaster.io/docs/app-config
Category: App Config
Status: available
Product: Roku Launch Kit
Summary: Platform-specific app behavior, branding, layout, and feature visibility for connected TV and mobile clients.

# App Config

**Location:** MediaBlaster → **App Config** → **App Settings** tab

Configure how connected apps (starting with the MediaBlaster Roku app) behave, look, and navigate. Settings are stored in WordPress and served publicly to clients via the REST config endpoint.

This is **not** API discovery — the app must already know your WordPress site URL to request config. Do not store `apiBaseUrl`, `apiOrigin`, secrets, or private credentials here.

## Platform tabs

| Tab | Status |
|-----|--------|
| **App Settings** (`platform=roku`) | Available |
| Mobile, Google TV, Fire TV, Apple TV | Planned — same page will gain additional tabs |

## Sections (App Settings tab)

| Section | Purpose |
|---------|---------|
| **General** | App name, debug mode |
| **Content Availability** | VOD, movies, series, categories, search, continue watching |
| **Branding** | Colors, fallback images, card/poster aspect ratios |
| **Links** | Support and privacy URLs |
| **Sidebar** | Sidebar visibility and widths |
| **Navigation Features** | Which destinations appear in app navigation (`features` object) |
| **Labels** | Custom UI labels (`labels` object) |
| **Homepage Layout** | Home screen layout toggles (`layout` object) |
| **Home Tag Rows** | Tag-based home row settings (`homeTagRows` object) |
| **Boot** | Startup behavior (`boot` object) |
| **REST Endpoint** | Read-only display of the public config URL |

Each field includes inline help text under its label. Section titles include a short description.

## REST endpoint

```
GET /wp-json/mediablaster/v3/config?platform=roku
```

- Public, read-only (no authentication required)
- Default `platform` query value: `roku`
- Unsupported platform → `400 mediablaster_invalid_platform`

See [REST API — App Config](rest-api-app-config.md) for the response shape.

**Not the same as** `GET /app/config` — that route returns subscription/Stripe client configuration when the subscriptions module and REST API are enabled. See [Subscriptions and Apps API](rest-api-subscriptions.md).

## Defaults and saving

- If nothing has been saved, the endpoint returns built-in Roku defaults immediately.
- `homeRows` is always `[]` in v1 (no admin UI yet).

## Related guides

- [REST API — App Config](rest-api-app-config.md)
- [REST API Overview](rest-api-overview.md)
- [Getting Started](getting-started.md)

## Captions, Trickplay, and Advertising

URL: https://www.mediablaster.io/docs/metabox-captions-trickplay-ads
Category: Content editor
Summary: Closed captions, BIF trickplay files, validity dates, and per-video ad breaks.

# Captions, Trickplay, and Advertising Metaboxes

These metaboxes appear on video posts when **Enable Legacy Controls** (Legacy Controls section on General Settings) and the specific Meta Controls sub-options are on. See [General Settings → Legacy Controls](general-settings.md#legacy-controls).

## Closed Captions / Subtitles

**Metabox:** Closed Captions/Subtitles

Add repeatable caption tracks:

| Field | Description |
|-------|-------------|
| **File URI** | URL to `.vtt` (WebVTT) or `.srt` file. WebVTT works on Roku and HTML5; SRT is Roku-only. |
| **Language** | BCP 47 language code (e.g. `en`, `es`). |
| **Type** | CLOSED_CAPTION or SUBTITLE |

Convert SRT to VTT with online tools if needed for cross-platform support.

## Trickplay (deprecated)

**Metabox:** Trickplay — **Deprecated in 3.0.0**

BIF trickplay files enable scrub preview thumbnails on Roku:

| Field | Description |
|-------|-------------|
| **BIF file URI** | URL to `.bif` file |
| **BIF definition** | HD or FHD resolution |

Avoid new BIF workflows unless maintaining legacy Roku channels.

## Advanced Controls

**Metabox:** Advanced Controls

| Field | Description |
|-------|-------------|
| **Validity start date** | Content available from this date |
| **Validity end date** | Content expires after this date |

Useful for licensed content windows and live-event replays.

## Advertising Controls

**Metabox:** Advertising Controls (not shown on Series posts)

Configure per-video ad breaks when feed ad type is **Scheduled** or **Scheduled w/ Automatic Fallback** (from prior configuration or JSON import).

| Field | Description |
|-------|-------------|
| **Ad breaks** | Repeatable cue points (time offsets) |
| **Custom mid-roll timer** | Override default mid-roll interval for automatic modes |

## Enabling these metaboxes

1. **General Settings → Enable Legacy Controls** — on
2. Enable the specific control: Subtitles, Trickplay, Advanced, or Advertising

## Related guides

- [General Settings](general-settings.md)

## Series and Episodes

URL: https://www.mediablaster.io/docs/metabox-series-episodes
Category: Content editor
Summary: Configure series containers, seasons, episode numbers, and playlists.

# Series and Episodes

MediaBlaster supports episodic content through **Series** and **Episodes** custom post types.

## Series post type

**Location:** WP Admin → **Series**

Each series post represents a show or collection. The **Series Data** metabox includes:

| Field | Description |
|-------|-------------|
| **Series type** | Genre/format classification (e.g. episodic, documentary). |
| **Release date** | Original or premiere date for feed metadata. |
| **Attached episodes playlist** | Ordered list of episode posts belonging to this series. |
| **Series thumbnail** | Artwork for series rows on Roku and web. |
| **Genres** | Browse metadata for the series. |

Attach episodes using the playlist/attached posts control — order here determines episode sequence in feeds.

## Episodes post type

**Location:** WP Admin → **Episodes**

Each episode is a video post with standard [Video Data](metabox-video-data.md) plus sidebar fields:

| Field | Description |
|-------|-------------|
| **Season number** | Season index (e.g. 1, 2). |
| **Episode number** | Episode index within the season. |

## Enabling series

Turn on **Enable Series** under [General Settings](general-settings.md). Both Series and Episodes post types register together.

## Feed behavior

When series are enabled in your feed configuration, the JSON feed at `/wp-json/tv/roku/` outputs a `series` array with nested seasons and episodes referencing episode content IDs and stream URLs. View or download the feed under [Import and Export](import-export.md).

## Tips

- Publish episodes before attaching them to a series playlist.
- Use consistent season/episode numbering — gaps may confuse Roku season browsers.
- Tag episodes for feed category recipes when using tag-based categories (configured via JSON import).

## Related guides

- [Video Data metabox](metabox-video-data.md)
- [Import and Export](import-export.md)

## Subscription Access Metabox

URL: https://www.mediablaster.io/docs/metabox-subscription-access
Category: Content editor
Summary: Gate individual videos by tier, access group, trials, and feed visibility.

# Subscription Access Metabox

**Location:** Post editor sidebar, below Featured Image, on premium-capable post types when subscriptions are enabled

Control who can watch each video and how unauthorized viewers experience locked content.

## Prerequisites

- Subscriptions enabled via `WPST_SUBSCRIPTIONS_ENABLED` in `wp-config.php` (see [General Settings](general-settings.md))

## Fields

| Field | Description |
|-------|-------------|
| **Access level** | Free, any subscriber, specific tier, or specific access group |
| **Required tier** | When access level is tier-specific, choose the plan |
| **Required access group** | When access level is group-specific, choose the bundle |
| **Allow trial access** | Let trialing subscribers watch this item |
| **Hide from public feeds** | Exclude from JSON feeds even if published |
| **Unauthorized behavior** | Show locked message vs hide completely (overrides site default) |

Defaults for new posts come from [Subscriptions General](subscriptions-general.md).

## Feed and player behavior

- `[mediablaster_player]` and `[tv-video-player]` respect entitlements — non-subscribers see a locked player overlay (poster + subscribe/login message) or nothing when **Hide completely** is configured.
- Playable video URLs are never output in HTML when access is denied.
- Public Roku feed is unchanged unless **Apply subscription rules to legacy IPTV feeds** is enabled globally.

## Workflow example

1. Create a **Premium** access group with sports content.
2. Link the group to a **Sports** tier.
3. On each sports video, set access level to that group or tier.
4. Subscribers on the Sports tier can play; others see the locked state.

## Related guides

- [Subscriptions Overview](subscriptions-overview.md)
- [Access Groups](subscriptions-access-groups.md)
- [Shortcodes](shortcodes.md)

## Video Data Metabox

URL: https://www.mediablaster.io/docs/metabox-video-data
Category: Content editor
Summary: Media URL, duration, quality, genres, and parental rating on video posts.

# Video Data Metabox

**Location:** Post editor on Movies, Short Videos, and Episodes

The **Video Data** metabox contains required technical metadata for IPTV feeds and the HTML5 player.

## Fields

| Field | Description |
|-------|-------------|
| **Media URL** | Direct HLS (`.m3u8`) or MP4 URL. YouTube URLs are not supported. |
| **Duration** | Length in seconds — used in feed JSON and players. |
| **Video Format** | Stream type indicator (e.g. HLS, MP4). |
| **Quality** | Resolution label (e.g. HD, FHD, 4K). |
| **Genres** | Comma-separated or selected genres for browse/filter metadata. |
| **Parental Rating** | Content rating for platform compliance (e.g. G, PG, TV-14). |

## Best practices

- Use CDN or Vimeo HLS URLs that allow direct playback on Roku and HTML5.
- Match duration to actual file length — incorrect values break trickplay and ad scheduling.
- Set featured images separately — they appear as thumbnails in feeds.

## Vimeo import

When **Enable Vimeo Integration** is on in General Settings, use the [Vimeo metabox](metabox-vimeo-import.md) **Load Video Data** button to populate URL, duration, quality, tags, and optionally title/description.

## Feed output

Values save to `rovidx_smarttv_*` post meta and appear in the [Content REST API](rest-api-content.md) as the `media`, `taxonomy`, and related fields. Missing Media URL or Duration may cause playback or feed issues on devices.

## Related guides

- [Getting Started](getting-started.md)
- [Series and Episodes](metabox-series-episodes.md)
- [Shortcodes](shortcodes.md)

## Vimeo Metabox

URL: https://www.mediablaster.io/docs/metabox-vimeo-import
Category: Content editor
Summary: Import single videos from Vimeo and optional upload to Vimeo.

# Vimeo Metabox

**Location:** Post editor on enabled video post types (Movies, Short Videos, Episodes)

The **Vimeo** metabox connects individual posts to Vimeo Pro/Business videos.

## Vimeo URL field

Paste a Vimeo video URL (e.g. `https://vimeo.com/123456789`) into **Vimeo URL**, then click **Load Video Data**.

When [Vimeo is connected](integrations-vimeo-oauth.md), MediaBlaster fetches:

- HLS stream URL → **Media URL**
- Duration, quality, format
- Tags and description (when [Vimeo Settings](vimeo-settings.md) allow)
- Title (when title import is enabled)
- Featured image thumbnail

Imported values populate `rovidx_smarttv_*` meta used by Roku feeds.

## Upload to Vimeo

When **Enable Vimeo Uploads** is on and OAuth is connected, an **Upload to Vimeo** panel appears:

1. Select a local video file
2. Start upload — progress polls via AJAX
3. On completion, the Vimeo URL and metadata can be loaded into the post

Requires sufficient Vimeo account storage and upload API permissions.

## Prerequisites

- **Enable Vimeo Integration** on [General Settings](general-settings.md)
- [Integrations (Vimeo OAuth)](integrations-vimeo-oauth.md) completed
- Import preferences under [Vimeo Settings](vimeo-settings.md)

## Bulk alternative

For many videos, use [Vimeo Mass Import](vimeo-mass-import.md) instead of per-post loading.

## Related guides

- [Video Data metabox](metabox-video-data.md)
- [Vimeo Settings](vimeo-settings.md)

## MediaBlaster Player

URL: https://www.mediablaster.io/docs/mediablaster-player
Category: Front-end
Summary: Embed the MediaBlaster streaming player with Video.js, shortcode, Gutenberg block, Elementor widget, and skins.

# MediaBlaster Player

The MediaBlaster player embeds video on WordPress pages and posts. **Video.js** is the default playback engine with a safe **native HTML5 fallback**, multi-source HLS/DASH/MP4 support, caption/chapter/thumbnail tracks, and subscription-aware locked states.

The shortcode, Gutenberg block, and Elementor widget all use the same player. Locked or premium content never exposes playable source URLs in HTML when access is denied.

## Using the MediaBlaster Player shortcode

```
[mediablaster_player]
```

## Legacy shortcode (still supported)

```
[tv-video-player]
```

Both shortcodes use the same renderer. New sites should prefer `[mediablaster_player]`.

Example with skin:

```
[mediablaster_player id="123" skin="streaming"]
```

## Using the MediaBlaster Player Gutenberg block

1. In the block editor, click **+** and search for **MediaBlaster Player** (category: **Media**).
2. Insert the block and open the sidebar panels: **Video Source**, **Player Display**, **Playback Options**, **Tracks**, **Advanced**.
3. Choose a **Video Post ID** (search or numeric ID). The block **imports** HLS/MP4, poster, and track URLs from that post’s MediaBlaster meta into the sidebar (editable). You can also enter direct URLs manually.
4. Publish — the player appears on the live page.

Imported HLS/MP4 URLs in the sidebar are **for reference only** when a **Video Post ID** is set. The frontend always loads **fresh URLs from that video post** on each page view (same as the shortcode). This matters for Vimeo and other signed CDN URLs that expire.

**Use URL fields instead of post meta** (Advanced) applies only when **no video post** is selected (manual URL mode). The toggle is disabled when a post ID is set.

If URL fields stay empty after selecting a post, reload the editor or re-select the video — playback still works from post meta when only **Video Post ID** is set.

The editor shows a live preview when a source is configured. Subscription and source resolution behave the same as on the published page.

## Using the MediaBlaster Player Elementor widget

Requires [Elementor](https://elementor.com/) (Elementor Pro not required).

1. Edit a page with Elementor.
2. Search the widget panel for **MediaBlaster Player** (category **MediaBlaster**).
3. Configure **Source mode**:
   - **Current Post** — uses the post ID of the page being viewed. On **Theme Builder** templates (e.g. single `movies`), set the sample post under the template **Preview Settings** (gear → Preview Settings → choose a movie); the editor canvas uses that preview post, not the `elementor_library` template post itself.
   - **Select Post** — pick a video from the dropdown or enter a Post ID.
   - **Direct URLs** — HLS/DASH/MP4 fields only (optional Post ID for poster/meta fallback).
4. Adjust display, playback, and track settings in the remaining sections.

**Editor preview:** The Elementor canvas shows the **same live player** as the published page, not a text-only placeholder. If no source is configured yet, a dashed hint box explains what to set. Subscription-locked videos show the locked state in the editor too.

Example: drag **MediaBlaster Player** onto the page, set **Current Post** on a single movie template, or **Select Post** with a specific video ID.

## Choosing a source

| Method | Best for |
|--------|----------|
| Post ID (shortcode `id`, block **Video Post ID**, Elementor **Select Post**) | Videos with MediaBlaster meta (`rovidx_smarttv_URL`, format, captions, BIF) |
| Direct URLs | External streams, landing pages without a video CPT post |
| Current post context | `[mediablaster_player]` with no `id` on a movie/episode singular template |

URL priority when overrides are set: `hls` → `dash` → `mp4_1080`–`360` → `url` → `mp4` → post meta. See [Source resolution](#source-resolution) below.

Enabled video post types depend on **MediaBlaster → General Settings** (movies, short videos, episodes). The block editor searches these types via AJAX; Elementor lists up to 50 recent published videos per type.

## Selecting a player skin

| Skin | Use case |
|------|----------|
| `default` | General site embeds |
| `streaming` | TV-style layouts |
| `creator` | Creator-focused pages |

Set via shortcode `skin="streaming"`, block **Player Display → Skin**, or Elementor **Player Display → Skin**.

## Adding captions

- **From post meta:** use default behavior (`captions="true"` on shortcode, or leave caption URL empty in block/widget).
- **Override with WebVTT:** `caption="https://…/en.vtt"` plus `caption_label` and `caption_lang`.
- **Subtitles track:** `subtitles` URL with `subtitles_label` / `subtitles_lang`.

## Adding chapters

- **Boolean (default):** `chapters="true"` loads chapter behavior from post meta when available.
- **WebVTT URL:** `chapters="https://…/chapters.vtt"` with optional `chapters_label` and `chapters_lang`.

Configure in the block/widget **Tracks** panel or shortcode attributes.

## Adding thumbnail/storyboard tracks

- **BIF from meta:** `thumbnails="true"` (default) loads `rovidx_smarttv_bif` when present.
- **WebVTT storyboard:** `thumbnails="https://…/thumbnails.vtt"`.

BIF scrubber UI on the progress bar is not implemented yet; metadata is stored for future use.

## Autoplay and muted behavior

Most browsers **block autoplay with sound**. For reliable autoplay, enable **Muted** as well as **Autoplay**.

The Gutenberg block shows a warning in the sidebar when autoplay is on and muted is off. Elementor includes the same guidance in control help text.

## Native fallback mode

Force native HTML5 (skip Video.js):

```
[mediablaster_player player_engine="native"]
```

Or set **Player engine → Native HTML5** in the block or Elementor widget. If Video.js is unavailable, the player falls back automatically.

## Basic examples

Current post context:

```
[mediablaster_player]
```

Specific video post:

```
[mediablaster_player id="123"]
```

Direct MP4 URL:

```
[mediablaster_player mp4="https://example.com/video.mp4"]
```

HLS stream:

```
[mediablaster_player hls="https://example.com/master.m3u8"]
```

DASH stream:

```
[mediablaster_player dash="https://example.com/manifest.mpd"]
```

Multiple MP4 qualities:

```
[mediablaster_player mp4_1080="https://example.com/video-1080.mp4" mp4_720="https://example.com/video-720.mp4" mp4_480="https://example.com/video-480.mp4"]
```

Poster override:

```
[mediablaster_player id="123" poster="https://example.com/poster.jpg"]
```

Autoplay (requires muted for most browsers):

```
[mediablaster_player id="123" autoplay="true" muted="true"]
```

Vertical video:

```
[mediablaster_player id="123" aspect_ratio="9:16"]
```

Captions (WebVTT):

```
[mediablaster_player caption="https://example.com/captions.vtt" caption_label="English" caption_lang="en"]
```

Subtitles:

```
[mediablaster_player subtitles="https://example.com/es.vtt" subtitles_label="Spanish" subtitles_lang="es"]
```

Chapters (WebVTT):

```
[mediablaster_player chapters="https://example.com/chapters.vtt" chapters_label="Chapters" chapters_lang="en"]
```

Thumbnail/storyboard VTT:

```
[mediablaster_player thumbnails="https://example.com/thumbnails.vtt"]
```

Legacy BIF trickplay URL (stored for future scrubber UI):

```
[tv-video-player bif="https://example.com/storyboard.bif"]
```

Player skins:

```
[mediablaster_player skin="streaming"]
[mediablaster_player skin="creator"]
```

Native HTML5 fallback (skip Video.js):

```
[mediablaster_player player_engine="native"]
```

## Player engine

Default engine: **videojs**.

- Video.js loads only when a player is rendered on the page (not globally).
- If bundled Video.js files are missing, or another plugin already registered Video.js, the player adapts automatically.
- If Video.js is unavailable, playback falls back to native HTML5 without breaking the page.

Bundled assets live at `public/vendor/videojs/` inside the plugin. See that folder’s README for upgrade instructions.

## Supported attributes

| Attribute | Default | Description |
|-----------|---------|-------------|
| `id` | current post | Video post ID |
| `player_engine` | `videojs` | `videojs` or `native` |
| `hls` | — | HLS master URL (`.m3u8`) |
| `dash` | — | DASH manifest URL (`.mpd`) |
| `mp4_1080` | — | 1080p MP4 URL |
| `mp4_720` | — | 720p MP4 URL |
| `mp4_480` | — | 480p MP4 URL |
| `mp4_360` | — | 360p MP4 URL |
| `url` | — | Generic video URL override |
| `mp4` | — | MP4 URL override |
| `type` | auto | Force format: `hls`, `mp4`, `dash`, etc. |
| `poster` | featured image | Poster image URL |
| `max_width` | `1920px` | CSS max-width |
| `aspect_ratio` | `16:9` | `16:9`, `4:3`, `1:1`, `9:16`, `21:9` |
| `skin` | `default` | `default`, `streaming`, `creator` |
| `controls` | `true` | Show player controls |
| `preload` | `metadata` | `none`, `metadata`, `auto` |
| `autoplay` | `false` | Autoplay when allowed |
| `loop` | `false` | Loop playback |
| `muted` | `false` | Mute audio |
| `playsinline` | `true` | Mobile inline playback |
| `start_time` | `0` | Seek to seconds on load |
| `class` | — | Extra CSS classes |
| `bif` | — | Legacy BIF URL or VTT storyboard alias |
| `captions` | `true` | Load caption tracks from post meta |
| `caption` | — | Single captions VTT URL |
| `caption_label` | English | Captions track label |
| `caption_lang` | `en` | Captions track language |
| `subtitles` | — | Single subtitles VTT URL |
| `subtitles_label` | English | Subtitles track label |
| `subtitles_lang` | `en` | Subtitles track language |
| `captions_json` | — | JSON array of multiple caption/subtitle tracks |
| `chapters` | `true` | Boolean flag, or chapters VTT URL |
| `chapters_label` | Chapters | Chapters track label |
| `chapters_lang` | `en` | Chapters track language |
| `thumbnails` | `true` | Boolean flag for BIF meta, or thumbnails VTT URL |
| `thumbnail_label` | Thumbnails | Thumbnail metadata track label |
| `resume` | `false` | Reserved for future resume watching |
| `autoplay_next` | `false` | Reserved for future playlist autoplay |
| `locked_behavior` | `overlay` | `overlay` or `message` when access denied |

### Dual-mode attributes

- **`thumbnails`**: `true`/`false` controls BIF meta loading; a URL value sets a WebVTT metadata track.
- **`chapters`**: `true`/`false` sets the chapters feature flag; a URL value adds a WebVTT chapters track.
- **`captions`**: `false` disables all caption/subtitle output including post meta.

## Source resolution

URL priority:

1. Shortcode `hls`
2. Shortcode `dash`
3. Shortcode `mp4_1080`, `mp4_720`, `mp4_480`, `mp4_360`
4. Shortcode `url`
5. Shortcode `mp4`
6. Post meta `rovidx_smarttv_URL`
7. Fire Creator add-on MP4 meta (when active)

Format detection uses explicit args, post meta `rovidx_smarttv_format`, or URL extension (`.m3u8`, `.mpd`, `.mp4`).

For HLS (`.m3u8`), the player follows master-playlist redirects server-side before rendering (common for Vimeo and other CDNs). This ensures variant playlists and segments load from the CDN origin with proper CORS instead of failing with a perpetual spinner.

Captions load from post meta `rovidx_smarttv_cc` when `captions="true"`.

BIF trickplay loads from post meta `rovidx_smarttv_bif` when `thumbnails="true"` (boolean mode).

## Subscription access

When subscriptions are enabled, the player checks entitlements before outputting playable sources.

- **Show locked** — Branded overlay with poster; no video URL in markup
- **Hide completely** — Empty output (no player rendered)
- Use `locked_behavior="message"` for legacy plain-text locked message

See [Subscription Access Metabox](metabox-subscription-access.md).

## Troubleshooting

### Block shows poster but no play button or controls (shortcode works)

**Typical signs:** HLS or segments may load in the Network tab; no JavaScript errors; Video.js poster visible; no big play icon or control bar.

**Cause:** Video.js can end up in `vjs-controls-disabled` when ingesting a `<video class="video-js">` element without a native `controls` attribute, even when `data-controls="true"` is on the wrapper.

**Check in browser DevTools:**

```js
const w = document.querySelector('[data-mediablaster-player]');
const vjs = w?.querySelector('.video-js');
console.log({
  dataControls: w?.getAttribute('data-controls'),
  controlsDisabled: vjs?.classList.contains('vjs-controls-disabled'),
  bigPlayDisplay: getComputedStyle(w.querySelector('.vjs-big-play-button')).display
});
```

**Expect when healthy (paused):** `dataControls` is `"true"`, `controlsDisabled` is `false`, `bigPlayDisplay` is `"block"`.

**Also verify:** hard-refresh the page so cached scripts are cleared; block has a valid **Video Post ID**; compare with `[mediablaster_player id="SAME_ID"]` on a test page. If the shortcode works but the block does not, update MediaBlaster to the latest version.

### Block does not play but Network shows HLS requests

1. Confirm **Video Post ID** points to a published video with `rovidx_smarttv_URL` (or overrides in manual URL mode).
2. Do not rely on stale HLS URLs saved in block JSON for post-backed videos — playback uses post meta, not expired sidebar URLs.
3. See [Video.js controls](#block-shows-poster-but-no-play-button-or-controls-shortcode-works) above if the stream loads but the UI is missing.

### Player assets missing (no init at all)

- Confirm the page includes the player block or shortcode and is not loading a stripped template that omits scripts.
- Hard-refresh or clear site cache so Video.js and player scripts load.
- Check the browser console for blocked or failed script requests.

### Editor: Controls toggle looks off for new blocks

The block defaults **Controls** to on. If the sidebar showed Controls off before saving, older posts may have `controls: false` in block JSON — re-enable **Controls** under **Playback Options** and update the post.

### Subscription locked

No playable `<source>` in HTML when access is denied — expected. See [Subscription access](#subscription-access).

## Not available yet

These features are not part of the player today:

- BIF scrubber UI on the progress bar
- Resume watching / watch progress storage
- Continue Watching shelf
- Analytics dashboard
- Autoplay next episode logic
- Chromecast / AirPlay / VAST ads

## Related guides

- [Shortcodes](shortcodes.md)
- [Podcast Audio Player](audio-player.md) — separate player for `podcast_episode` audio (not Video.js)
- [Video Data metabox](metabox-video-data.md)
- [Closed Captions & Trickplay](metabox-captions-trickplay-ads.md)

## Podcast Audio Player

URL: https://www.mediablaster.io/docs/audio-player
Category: Front-end
Summary: Embed a polished podcast episode audio player via shortcode, Gutenberg block, Elementor, or the default episode template.

# Podcast Audio Player

The MediaBlaster **Podcast Audio Player** embeds episode audio on WordPress pages. The shortcode, Gutenberg block, Elementor widget, and public episode template all use the same player, so playback, premium locking, and styling stay consistent.

**Requires:** **Enable Podcasts** on [General Settings](general-settings.md).

## What it does

- Resolves audio from the episode’s canonical source (upload or external URL) via `Wp_Smart_Tv_Podcast_Tools`
- Renders accessible markup with a native `<audio>` element and custom controls (play/pause, skip ±15s/30s, progress, speed)
- Respects **premium** episodes: locked message only — **no audio URL** in HTML for unauthorized public viewers
- Enqueues scoped CSS/JS only when the player appears on the page

See also: [Podcast Episodes](podcast-episodes.md) for configuring episode media.

## Shortcodes

**Preferred:**

```
[mediablaster_audio_player]
```

**Aliases (same behavior):**

```
[mediablaster_podcast_player]
[wpst_audio_player]
```

### Examples

Current episode (on a single `podcast_episode` page):

```
[mediablaster_audio_player]
```

Specific episode:

```
[mediablaster_audio_player id="123"]
```

With options:

```
[mediablaster_audio_player id="123" style="compact" theme="dark" show_download="true"]
```

## Gutenberg block

- **Block name:** `mediablaster/audio-player`
- **Title:** MediaBlaster Audio Player
- **Category:** Widgets

In the block sidebar, set **Podcast Episode ID** and toggle display options (artwork, title, skip controls, speed, etc.). Without an episode ID, the editor shows a placeholder until an ID is set (or use the block on an episode page with ID `0` and rely on the current post — set the ID in the sidebar to the episode’s post ID for explicit previews).

## Elementor widget

When Elementor is active, find **MediaBlaster Audio Player** under the **MediaBlaster** category (or General).

Controls mirror the shortcode options: episode ID, display toggles, style, theme, and extra CSS class. The canvas preview matches the live site.

## Episode template

Public single episode pages (`single-podcast-episode.php`) use the audio player automatically for playable audio media. Video and oEmbed media are unchanged.

## Attributes and options

| Attribute / option | Default | Values | Description |
| ------------------ | ------- | ------ | ----------- |
| `id` | current post ID | post ID | `podcast_episode` post ID |
| `show_artwork` | `true` | bool | Episode or show artwork |
| `show_title` | `true` | bool | Episode title |
| `show_show_name` | `true` | bool | Linked podcast show name |
| `show_description` | `false` | bool | Excerpt or trimmed show notes |
| `show_meta` | `true` | bool | Date, duration, episode type |
| `show_download` | `false` | bool | Download link (only when audio is playable) |
| `show_speed` | `true` | bool | Playback speed selector |
| `show_skip` | `true` | bool | Skip back 15s / forward 30s |
| `show_progress` | `true` | bool | Progress range and time display |
| `theme` | `default` | `default`, `dark`, `minimal` | Color theme |
| `style` | `card` | `card`, `compact`, `inline`, `minimal` | Layout style |
| `class` | — | string | Extra CSS classes on the wrapper |

Shortcode booleans accept `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`.

## Premium episodes

For **premium** episodes in the **public** context, normalized episode data clears `canonical_audio`. The player shows the **Premium Episode Locked Message** from [Podcast Settings](podcast-settings.md) (when subscriptions are enabled) and does **not** output:

- `<audio src="...">`
- Download links
- `data-audio-url` or similar

This matches RSS and public page behavior; subscription entitlement on public WordPress pages is not upgraded by the player alone.

## Audio sources

Episode audio is resolved in this order (see episode **Audio source** meta):

1. **Upload** — Media Library file (CMB2 stores attachment ID in `{field}_id` meta)
2. **External URL** — Direct link to an audio file (must be playable MIME, not an embed-only page)

If neither is configured, visitors see *Audio is not available for this episode.* Administrators see a hint to configure upload or URL in the episode editor.

## Related docs

- [Shortcodes](shortcodes.md)
- [MediaBlaster Player](mediablaster-player.md) (video)
- [Podcasts overview](podcasts.md)
- [Podcast RSS](podcast-rss.md)

## Shortcodes

URL: https://www.mediablaster.io/docs/shortcodes
Category: Front-end
Summary: Embed video and podcast audio players, subscription checkout, and account management on pages.

# Shortcodes

MediaBlaster provides shortcodes for embedding video, podcast audio, and subscription UI in WordPress pages and posts.

## Video player

**Preferred:**

```
[mediablaster_player]
```

**Legacy (still supported):**

```
[tv-video-player]
```

Embeds the HTML5 HLS/MP4 player for the current post context. Use on single video templates or with an explicit post ID:

```
[mediablaster_player id="123"]
```

See [MediaBlaster Player](mediablaster-player.md) for full attribute reference, the **MediaBlaster Player** Gutenberg block, Elementor widget, skins, and **troubleshooting** (e.g. block poster with no controls).

The block and shortcode use the same player. With a **Video Post ID**, both load fresh stream URLs from post meta on each page view.

When subscriptions are enabled, playback respects [Subscription Access](metabox-subscription-access.md) rules.

## Podcast audio player

**Preferred:**

```
[mediablaster_audio_player]
```

**Aliases (same behavior):**

```
[mediablaster_podcast_player]
[wpst_audio_player]
```

Embeds the podcast episode audio player for the current `podcast_episode` or a specific episode ID:

```
[mediablaster_audio_player id="123"]
```

See [Podcast Audio Player](audio-player.md) for display options, Gutenberg block, Elementor widget, and premium locking.

**Requires:** podcasts enabled.

## Subscribe page

```
[wpst_subscribe]
```

Lists active subscription tiers with price, billing interval, trial days, and **Subscribe** buttons (Stripe checkout when configured).

Optional attribute:

```
[wpst_subscribe tier="3"]
```

Shows only tier ID 3.

**Requires:** subscriptions enabled, user logged in for checkout buttons, Stripe enabled with mapped Price IDs.

## Single-tier checkout button

```
[wpst_stripe_checkout tier_id="1" button_text="Subscribe Now"]
```

Optional attributes: `class`, `success_url`, `cancel_url`.

## Account page

```
[wpst_account]
```

Shows the logged-in user's subscription status, renewal/trial dates, cancel-at-period-end notice, and **Manage Billing** (Stripe Customer Portal) when applicable.

## Typical page setup

| Page slug | Shortcode |
|-----------|-----------|
| `/subscribe/` | `[wpst_subscribe]` |
| `/account/` | `[wpst_account]` |
| Video landing pages | `[mediablaster_player]` or `[tv-video-player]` |
| Podcast episode pages | `[mediablaster_audio_player]` (also used in the default episode template) |

Match slugs to **Subscribe page slug** and Stripe redirect URLs under [Payment Providers](subscriptions-payment-providers.md).

## Logged-out visitors

Subscribe and checkout shortcodes show a login/register prompt with links to `wp_login_url()` and registration when the user is not signed in.

## Related guides

- [Stripe Checkout Setup](stripe-checkout-setup.md)
- [Subscriptions Overview](subscriptions-overview.md)
- [Video Data metabox](metabox-video-data.md)
- [Podcast Audio Player](audio-player.md)

## General Settings

URL: https://www.mediablaster.io/docs/general-settings
Category: General Settings
Summary: Enable post types, Vimeo integration, and legacy meta controls; subscriptions are enabled via wp-config.php.

# General Settings

**Location:** MediaBlaster → General Settings (first tab on the main settings page)

These options control which content types appear in your admin menu and whether legacy metaboxes are available. Subscriptions are **not** configured on this screen unless the module is already enabled in `wp-config.php`.

## Media Post Types

Choose which custom post types MediaBlaster registers on your site. Only enabled types appear in the admin sidebar and in feed builders.

| Setting | Description |
|---------|-------------|
| **Enable Movies** | Adds the **Movies** post type for long-form standalone video. |
| **Enable Short-form Videos** | Adds the **Short Videos** post type for clips and short content. |
| **Enable Series** | Adds **Series** and **Episodes** post types for episodic content. |

## Podcasts

Podcasts are **off by default**. Turn on **Enable Podcasts** on this tab to register **Podcast Shows** and **Podcast Episodes**.

After enabling, save and reload — a **Podcast Settings** tab appears with public page URLs, RSS options, and (when subscriptions are enabled) premium episode display settings. See [Podcasts Overview](podcasts.md) and [Podcast Settings](podcast-settings.md).

| Setting | Description |
|---------|-------------|
| **Enable Podcasts** | Master switch for podcast shows, episodes, metadata, RSS, and REST. |

## Vimeo Integration

Vimeo is **off by default**. Turn on **Enable Vimeo Integration** to show Integrations and Vimeo Settings tabs, the post editor Vimeo metabox, **MediaBlaster → Vimeo Mass Import**, OAuth, and import/upload AJAX.

| Setting | Description |
|---------|-------------|
| **Enable Vimeo Integration** | When on, full Vimeo Pro/Business import and OAuth tools are available. When off, all Vimeo admin UI and API calls are hidden. Previously imported `rovidx_smarttv_*` meta is exposed via the [Content REST API](rest-api-content.md). |

See [Integrations (Vimeo OAuth)](integrations-vimeo-oauth.md), [Vimeo Settings](vimeo-settings.md), and [Vimeo Mass Import](vimeo-mass-import.md) when integration is enabled.

## Subscriptions

Subscriptions are **off by default**. Enable the module in `wp-config.php`:

```php
define( 'WPST_SUBSCRIPTIONS_ENABLED', true );
```

When enabled, MediaBlaster adds **MediaBlaster → Subscriptions**, subscription guides under **Docs**, REST routes at `/wp-json/mediablaster/v3/`, content gating, and shortcodes.

While subscriptions are disabled, the Subscriptions block does **not** appear on General Settings. After enabling via `wp-config.php`, General Settings may show a read-only **Enable Subscriptions** field (Coming Soon in the UI — the real switch remains `wp-config.php`).

See [Subscriptions Overview](subscriptions-overview.md) for full setup.

## Legacy Controls

Legacy controls reveal additional metaboxes on video posts for trickplay (BIF), closed captions, advanced scheduling, and per-video advertising. They are **enabled by default** on existing installs. This section appears after Subscriptions (when shown) and Vimeo Integration on the General Settings tab.

| Setting | Description |
|---------|-------------|
| **Enable Legacy Controls** | Master switch for the Meta Controls subsection below. Turn off to simplify the post editor. |

### Meta Controls

Shown when **Enable Legacy Controls** is on.

| Setting | Description |
|---------|-------------|
| **Enable Trickplay Support** | BIF trickplay files on video posts. **Deprecated in 3.0.0.** |
| **Enable Subtitle Support** | Closed captions and subtitle file fields. |
| **Enable Advanced Controls** | Validity start/end dates on videos. |
| **Enable Advertising Controls** | Per-video ad break configuration. |

When legacy controls are off, the Meta Controls fields are hidden entirely. See [Captions, Trickplay, and Advertising metaboxes](metabox-captions-trickplay-ads.md).

## Saving changes

Click **Save** at the bottom of the form. Switch fields persist an explicit off state so unchecked options stay off after reload.

## Related settings pages

| Page | Purpose |
|------|---------|
| [App Config](app-config.md) | Platform app branding and behavior for Roku and future clients (`mediablaster_app_config`) |
| [Podcast Settings](podcast-settings.md) | RSS and public podcast pages (when podcasts enabled) |
| [Vimeo Settings](vimeo-settings.md) | Import preferences and upload options (when Vimeo enabled) |
| [Integrations (Vimeo OAuth)](integrations-vimeo-oauth.md) | Connect your Vimeo account (when Vimeo enabled) |

## Import and Export

URL: https://www.mediablaster.io/docs/import-export
Category: General Settings
Summary: Import JSON feeds, export your catalog, and use the MediaBlaster v3 REST API.

# Import and Export

**Location:** MediaBlaster → General Settings → **Import/Export** tab

Use this tab to migrate content from another JSON feed source, download a snapshot of your current catalog, or integrate via the REST API.

## Import a JSON feed

1. Enter the **Direct Publisher Feed URL** — a publicly reachable URL that returns valid Roku Direct Publisher JSON.
2. Select **Import Type: Roku JSON**.
3. Click **Start Import** and watch the console for progress.

The importer creates WordPress posts and meta from movies, short-form videos, series, and related feed structures. Remote URLs are validated for safety before download.

### Import tips

- Back up your site before large imports.
- Ensure the post types you need are enabled under [General Settings](general-settings.md) first.
- Import requires administrator privileges and uses a secured AJAX endpoint.

## Export and API access

The **Export Direct Publisher (JSON)** section may still offer a downloadable JSON snapshot of your catalog. For integrations in 3.0.0, prefer the REST API:

### MediaBlaster v3 API base URL

```
https://YOUR-SITE.com/wp-json/mediablaster/v3
```

| Endpoint | Use |
|----------|-----|
| `GET /` | Discovery — enabled post types and feature flags |
| `GET /content` | Paginated published catalog |
| `GET /content/{id}` | Single item with media, taxonomy, access |

See [REST API Overview](rest-api-overview.md) and [Content API and Fields](rest-api-content.md) for full endpoint and field documentation.

### Testing the API

1. Open `GET /wp-json/mediablaster/v3` in a browser to confirm the API is registered.
2. Call `GET /wp-json/mediablaster/v3/content` to list published items.
3. Use Application Passwords or Bearer auth (subscriptions) for create/update operations.

### Subscription gating

REST content responses include `access` fields when subscriptions are enabled. Locked items may hide `media.url` from unauthorized viewers. Configure rules per post in the [Subscription Access metabox](metabox-subscription-access.md).

## Related guides

- [REST API Overview](rest-api-overview.md)
- [Content API and Fields](rest-api-content.md)
- [General Settings](general-settings.md)

## Integrations (Vimeo OAuth)

URL: https://www.mediablaster.io/docs/integrations-vimeo-oauth
Category: General Settings
Summary: Connect Vimeo Pro/Business with OAuth and API credentials.

# Integrations (Vimeo OAuth)

**Location:** MediaBlaster → General Settings → **Integrations** tab

Use this tab to connect your Vimeo Pro or Business account so MediaBlaster can fetch video metadata, HLS stream URLs, thumbnails, tags, and descriptions.

## Before you begin

1. Enable **Enable Vimeo Integration** on **MediaBlaster → General Settings** and save.
2. Log in to [Vimeo Developer](https://developer.vimeo.com/) and create an app (or open an existing one).
3. Note your app's **Client ID** and **Client Secret**.
4. You will need to add a **Redirect URI** from MediaBlaster into your Vimeo app settings.

## Step-by-step connection

1. Open **MediaBlaster → General Settings** and click the **Integrations** tab.
2. Copy the **Redirect URI** displayed on the page.
3. In your Vimeo app settings, add that URI to **Redirect URIs** and save.
4. Paste the **Client ID** and **Client Secret** into MediaBlaster and save settings.
5. Click **Connect Vimeo** and approve access on Vimeo's authorization screen.
6. Return to WordPress — the **Client Token** is saved automatically (you do not need to paste it manually).

## After connecting

- Use the **Vimeo URL** field on video posts and click **Load Video Data** to import a single video.
- Use **MediaBlaster → Vimeo Mass Import** for bulk imports (card grid, **Ready to Import** default, **Review & Import**). See [Vimeo Mass Import](vimeo-mass-import.md).
- Configure title/description import behavior under the [Vimeo Settings](vimeo-settings.md) tab.

## Troubleshooting

| Problem | What to try |
|---------|-------------|
| OAuth redirect fails | Confirm the Redirect URI in Vimeo matches exactly (including trailing slash if shown). |
| SSL certificate errors | Common on local dev environments. MediaBlaster prefers WordPress's CA bundle; check PHP/cURL on your host. |
| Token missing after connect | Re-save Client ID/Secret, then click Connect Vimeo again. |
| Existing token from older installs | Previously saved tokens under `rovidx_smart_tv_api_options` continue to work without re-authorizing. |

## Security

Only site administrators (`manage_options`) can view or change integration credentials. Client Secret fields use password-style inputs. Do not share API credentials publicly.

## Vimeo Settings

URL: https://www.mediablaster.io/docs/vimeo-settings
Category: General Settings
Summary: Control what Vimeo data is imported and optional upload features.

# Vimeo Settings

**Location:** MediaBlaster → General Settings → **Vimeo Settings** tab

Requires **Enable Vimeo Integration** on the General Settings tab. After connecting Vimeo on the [Integrations](integrations-vimeo-oauth.md) tab, use these options to control how imported data is applied to your WordPress posts.

## Import preferences

| Setting | Description |
|---------|-------------|
| **Title Import** | When enabled, Vimeo video titles can overwrite the WordPress post title during import. |
| **Description Import** | When enabled, Vimeo descriptions can populate the post content/body. |

Turn these off if you prefer to write your own titles and descriptions in WordPress and only pull stream URLs and technical metadata from Vimeo.

## Vimeo uploads

| Setting | Description |
|---------|-------------|
| **Enable Vimeo Uploads** | Shows an upload panel on supported video posts so you can push local files to Vimeo from the editor. Requires an active OAuth connection. |

When uploads are enabled and Vimeo is connected, editors see **Upload to Vimeo** controls on the Vimeo metabox. See [Vimeo metabox](metabox-vimeo-import.md).

## Refresh existing data

The **Refresh Existing Vimeo Data** button re-fetches metadata for posts that already have a saved Vimeo URL. Use this after bulk changes on Vimeo or when thumbnails and durations are out of date.

This operation runs via AJAX and may take time on large catalogs — run during low-traffic periods.

## Related guides

- [Vimeo OAuth setup](integrations-vimeo-oauth.md)
- [Vimeo Mass Import](vimeo-mass-import.md)
- [Vimeo metabox on posts](metabox-vimeo-import.md)

## Getting Started with MediaBlaster

URL: https://www.mediablaster.io/docs/getting-started
Category: Getting started
Status: available
Product: MediaBlaster WordPress Plugin
Summary: MediaBlaster turns WordPress into a media publishing platform — first-time setup and recommended workflow.

# Getting Started with MediaBlaster

MediaBlaster turns your WordPress site into a **media publishing platform**. You manage movies, short videos, series, episodes, and podcasts as custom post types, then deliver them to HTML5 players on your website, podcast apps via RSS, and connected devices through the REST API and IPTV-style JSON feeds.

## What you need

- WordPress 6.3 or newer
- PHP 7.4 or newer
- Video files hosted on a CDN or platform that provides direct HLS or MP4 URLs (Vimeo Pro/Business import is available when **Enable Vimeo Integration** is on in General Settings)
- Administrator access to configure plugin settings

## First-time setup checklist

1. **Enable post types** — Go to **MediaBlaster → General Settings** and turn on the content types you need (Movies, Short-form Videos, Series). See [General Settings](general-settings.md).
2. **Add video content** — Create posts under Movies, Short Videos, Episodes, or Series. Fill in the **Video Data** metabox with media URL, duration, and metadata. See [Video Data metabox](metabox-video-data.md).
3. **Connect Vimeo** (optional) — Enable **Vimeo Integration** on General Settings, then connect under **Integrations** and import via the post editor or Mass Import. See [Vimeo OAuth](integrations-vimeo-oauth.md).
4. **Enable Podcasts** (optional) — Turn on **Enable Podcasts** in General Settings to add Podcast Shows and Episodes, RSS feeds, and public pages. See [Podcasts Overview](podcasts.md).

## Typical workflows

### Publish a single video manually

1. Create a **Movie** or **Short Video** post.
2. Enter title, description, and featured image.
3. In **Video Data**, set the **Media URL** (HLS `.m3u8` or MP4), **Duration**, and **Quality**.
4. Save and preview with the `[tv-video-player]` shortcode on a page. See [Shortcodes](shortcodes.md).

### Import from Vimeo

Requires **Enable Vimeo Integration** on General Settings.

1. Connect Vimeo under **MediaBlaster → Integrations**.
2. Configure import preferences under **Vimeo Settings**.
3. Use **Load Video Data** on a post, or bulk-import via **Vimeo Mass Import** (select videos → **Review & Import**). See [Vimeo Mass Import](vimeo-mass-import.md).

### Enable subscriptions (optional)

Subscriptions are hidden until you opt in via `wp-config.php`:

1. Add `define( 'WPST_SUBSCRIPTIONS_ENABLED', true );` to `wp-config.php` and reload wp-admin.
2. Open **MediaBlaster → Subscriptions** to configure tiers, access groups, and Stripe.
3. Subscription guides appear under **MediaBlaster → Docs** once enabled.
4. Add `[wpst_subscribe]` and `[wpst_account]` pages. See [Subscriptions Overview](subscriptions-overview.md).

### Publish podcasts (optional)

Requires **Enable Podcasts** on General Settings.

1. Configure **[Podcast Settings](podcast-settings.md)** — public pages and RSS (save and reload after enabling podcasts).
2. Create a **Podcast Show** under **Podcasts → Add New Podcast**.
3. Fill in show metadata, artwork, and enable **RSS Enabled for This Show**.
4. Add episodes via **Add New Episode** on the show or **Podcasts → Podcast Episodes**.
5. On each episode, set **Episode Media** (audio upload or direct file URL) so RSS enclosures validate.
6. Public episode pages include the [Podcast Audio Player](audio-player.md) automatically; embed elsewhere with `[mediablaster_audio_player id="…"]` or the **MediaBlaster Audio Player** block.
7. Verify the feed at `/podcast-feed/{show-slug}/`. See [Podcast RSS](podcast-rss.md).

### Configure connected apps (Roku and future platforms)

1. Open **MediaBlaster → App Config → App Settings**.
2. Set app name, branding colors, navigation features, labels, and home layout.
3. Save — settings are served at `GET /wp-json/mediablaster/v3/config?platform=roku` for your Roku or other clients.
4. See [App Config](app-config.md) and [REST API — App Config](rest-api-app-config.md).

This endpoint is for **platform UI/behavior** (branding, navigation, layout). Subscription and Stripe client settings use a separate route: `GET /app/config` when subscriptions REST is enabled.

## REST API (3.0.0)

MediaBlaster exposes a JSON API for apps and integrations:

```
https://YOUR-SITE.com/wp-json/mediablaster/v3
```

Start with **GET** that URL for discovery links, then see the **REST API** section under **MediaBlaster → Docs**:

- [REST API Overview](rest-api-overview.md)
- [App Config](app-config.md) and [REST API — App Config](rest-api-app-config.md)
- [Content API and Fields](rest-api-content.md)
- [Vimeo REST API](rest-api-vimeo.md) (when Vimeo is enabled)
- [Subscriptions and Apps API](rest-api-subscriptions.md) (when subscriptions are enabled)
- [REST API — Podcasts](rest-api-podcasts.md) (when podcasts are enabled)
- [Podcast Audio Player](audio-player.md) (when podcasts are enabled)

## Important notes

- **YouTube is not supported** — YouTube does not provide direct stream URLs required for device playback.
- **Legacy Roku feed** (`/wp-json/tv/roku/`) is removed in 3.0.0 — use the REST content API or export tools instead.
- **Trickplay** is deprecated in 3.0.0 — prefer modern caption formats (WebVTT).

## Where to get help

Use **MediaBlaster → Docs** in your WordPress admin for guides organized by settings page and tab. **App Config** guides are always listed. Subscription guides are listed only when `WPST_SUBSCRIPTIONS_ENABLED` is true. Vimeo guides appear only when **Enable Vimeo Integration** is on in General Settings. Podcast guides appear only when **Enable Podcasts** is on. Field-level help tooltips (hover the label or `?` icon) appear on subscription settings screens when the module is enabled.

## Podcast Episodes

URL: https://www.mediablaster.io/docs/podcast-episodes
Category: Podcasts
Summary: Episode metadata, audio/video media, transcripts, chapters, premium access, and RSS fields.

# Podcast Episodes

**Admin menu:** Podcasts → Podcast Episodes / Add New Episode

Episodes belong to one **Podcast Show** via the Parent Podcast Show field (`rovidx_smarttv_podcast_show_id`).

## Episode data

| Field | Notes |
|-------|-------|
| Episode Type | Full, Trailer, or Bonus (RSS episode type) |
| Season / Episode Number | Optional integers |
| Duration | Manual entry (hh:mm:ss, mm:ss, or seconds) |
| Explicit | Inherit show default or override |
| Access Level | Free or Premium (premium teasers when subscriptions enabled) |
| Include in RSS | Default, Yes, or No — premium always excluded from RSS |
| Featured Episode | For show pages, apps, REST |
| Guest Name(s) | Optional text |

## Episode media

**Required for RSS:** at least one direct media source (audio recommended for podcast apps).

Audio and video each support **Uploaded File** or **External URL**:

| Source | Use for RSS |
|--------|-------------|
| **Audio Upload** | Yes — attach MP3/M4A via Media Library |
| **Audio External URL** | Yes — direct file URL (not a web page) |
| **Video Upload** | Yes — when show uses video-first priority or no audio |
| **Video External URL** | Yes — direct MP4 or stream URL; not YouTube/Vimeo pages |

Tips:

- Default show **RSS Media Priority** is **Audio First** — add audio for the widest app compatibility.
- If **Audio Source** is Uploaded File, you must complete the upload before saving.
- YouTube/Vimeo URLs work for embed playback on public pages but **do not** become RSS enclosures unless you set an **RSS Enclosure Override URL** with a direct file link.

## Public playback

The default episode template and embeds use the [Podcast Audio Player](audio-player.md) for direct audio files (`audio/*` MIME). Embed anywhere with:

```
[mediablaster_audio_player id="123"]
```

Video and oEmbed URLs still use the template’s native video/embed markup. Premium episodes show the locked message in the player without exposing audio URLs.

## Transcript

Plain-text transcript and optional transcript file upload (.txt, .vtt, .srt, .json). Exposed via REST in v1; not in RSS namespace yet.

## Chapters

Repeatable chapter rows: title + start time.

## Advanced RSS

Optional enclosure override URL, MIME type, and file size when the playback URL differs from the RSS enclosure URL (for example CDN or signed URLs).

## Admin warnings

If an episode is expected in RSS (published, free, show RSS on) but has no valid enclosure, a non-blocking notice appears at the top of the episode edit screen.

Check RSS status via REST field `rss_status`: `included`, `excluded`, or `missing_enclosure`.

## Creating from a show

From a Podcast Show edit screen, **Add New Episode** opens:

`post-new.php?post_type=podcast_episode&podcast_show={id}`

The Parent Podcast Show dropdown is pre-selected.

See [Podcast RSS](podcast-rss.md) for inclusion rules and troubleshooting empty feeds. See [Podcast Audio Player](audio-player.md) for shortcode, block, and Elementor options.

## Podcast RSS

URL: https://www.mediablaster.io/docs/podcast-rss
Category: Podcasts
Summary: Global and per-show RSS settings, feed URLs, inclusion rules, and enclosure resolution.

# Podcast RSS

## Enable feeds

Four requirements for a live feed with episodes:

1. **Enable Podcasts** ([General Settings](general-settings.md))
2. **Enable Podcast RSS Feeds** ([Podcast Settings](podcast-settings.md))
3. **RSS Enabled for This Show** (Podcast Show edit screen)
4. At least one **published free episode** with a **valid enclosure** (see below)

## Feed URL

Default pattern:

`/podcast-feed/{show-slug}/`

Customize the base with **Podcast RSS Feed Base** on the [Podcast Settings](podcast-settings.md) tab (default: `podcast-feed`).

The show edit screen **RSS Feed** side panel displays a read-only, copyable URL when global and show RSS are both enabled.

## Episode inclusion

Included when **all** are true:

- Published episode
- Assigned to the show
- Access level = Free
- Include in RSS = Default or Yes
- Valid RSS enclosure exists (direct media file URL or WordPress upload)

Excluded: draft, scheduled, private, premium, manual RSS No, missing enclosure.

Manual **Include in RSS = Yes** cannot override premium safety rules in v1.

## Enclosure resolution

Each episode needs media in **Episode Media** (or an **Advanced RSS** override).

Priority order:

1. **RSS Enclosure Override URL** (Advanced RSS metabox), if set
2. Show **RSS Media Priority** (audio-first or video-first)
3. Canonical uploaded file or direct external media URL

Accepted sources:

- **Audio Upload** or **Audio External URL** (MP3, M4A, etc.)
- **Video Upload** or **Video External URL** when show priority is video-first or audio is unavailable

Not accepted as enclosures:

- YouTube or Vimeo **page/player URLs** (embed playback only)
- Episodes with **Audio Source = Uploaded File** but no file attached
- Episodes with **Video Source = External URL** but an empty URL field

Uploaded files are stored by the WordPress Media Library. MediaBlaster reads the attachment ID from CMB2’s `{field}_id` meta key.

## RSS Readiness checklist

On each show edit screen, the **RSS Readiness** side panel verifies title, artwork, subtitle, owner, category, language, global RSS, show RSS, and at least one free published episode with a valid enclosure.

## Troubleshooting empty feeds

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Feed URL 404 | Rewrites not flushed | Save Podcast Settings, then **Settings → Permalinks → Save** |
| Feed loads, channel only, no `<item>` | `missing_enclosure` | Edit episode → **Episode Media** → upload audio or paste a direct file URL → Update |
| Side panel says RSS disabled | Global or show toggle off | Enable both RSS switches |
| Episode published but still missing | Premium or Include in RSS = No | Set Access = Free, Include in RSS = Default/Yes |

A non-blocking admin notice appears on episode edit when RSS is expected but no valid enclosure is found.

## v1 limitations

- Public feeds only (no private/tokenized feeds)
- Standard RSS 2.0 + basic iTunes tags — no Media RSS or transcript namespace yet

After changing RSS or public page bases, save Podcast Settings and visit **Settings → Permalinks → Save** if URLs do not resolve.

## Podcast Settings

URL: https://www.mediablaster.io/docs/podcast-settings
Category: Podcasts
Summary: Public page URLs, global RSS options, and premium episode display — separate tab from General Settings.

# Podcast Settings

**Location:** MediaBlaster → General Settings → **Podcast Settings** tab

This tab appears only after **Enable Podcasts** is on in **General Settings**. Save and reload wp-admin if you do not see it.

All options save to the same `rovidx_smart_tv_options` array as General Settings.

## Public Pages

| Setting | Description |
|---------|-------------|
| **Enable Podcast Public Pages** | When on, published shows and episodes get WordPress front-end URLs. Turn off for headless/API-only setups. Default: on when the key is unset. |
| **Podcast Public Page Base** | URL slug for show and episode pages. Default: `podcasts`. Example: `/podcasts/my-show/my-episode/`. |

## RSS Feeds

| Setting | Description |
|---------|-------------|
| **Enable Podcast RSS Feeds** | Global master switch for per-show RSS output. Must be on along with each show’s **RSS Enabled for This Show** checkbox. |
| **Podcast RSS Feed Base** | URL slug for feeds. Default: `podcast-feed`. Example: `/podcast-feed/my-show/`. |

Changing public or RSS bases may require visiting **Settings → Permalinks → Save Changes** if URLs 404.

## Premium Episodes

This section appears only when subscriptions are enabled (`WPST_SUBSCRIPTIONS_ENABLED` in `wp-config.php`).

| Setting | Description |
|---------|-------------|
| **Show Premium Episode Teasers** | When on, premium episodes can appear as locked teaser cards on public show pages. |
| **Premium Episode Locked Message** | Text shown on locked premium episode pages. |

Premium episodes are always excluded from public RSS feeds regardless of these settings.

## Podcast Status summary

When the tab loads, a summary box shows show count, episode count, RSS warnings, and (when subscriptions are enabled) premium episode count.

See also: [Podcasts Overview](podcasts.md), [Podcast RSS](podcast-rss.md).

## Podcast Shows

URL: https://www.mediablaster.io/docs/podcast-shows
Category: Podcasts
Summary: Create and manage Podcast Shows, metadata, distribution links, and the episodes panel.

# Podcast Shows

**Admin menu:** Podcasts → All Podcasts / Add New Podcast

## Show content

- **Title** — show name
- **Editor** — long show description / about page
- **Featured image** — show artwork (used in RSS and public pages)
- **Excerpt** — optional WordPress excerpt (show subtitle field is preferred for RSS/cards)

## Podcast Show Data

| Field | Purpose |
|-------|---------|
| Subtitle / Short Summary | RSS, apps, cards, previews |
| Main Host Name | Display and metadata |
| Credits / Contributors | Optional freeform credits |
| Owner Name / Email | RSS owner metadata |
| Language | RSS language (defaults from site locale) |
| Copyright | RSS copyright |
| Podcast App Category | Fixed top-level category list for directories |
| Default Explicit Setting | Inherited by episodes unless overridden |
| RSS Enabled for This Show | Per-show RSS toggle |
| RSS Media Priority | Audio-first or video-first for enclosures |

## Distribution Links

Optional Apple, Spotify, YouTube, Amazon, and website URLs for public show pages.

The **Generated RSS Feed URL** side panel is read-only. It shows a copyable URL when global RSS (**Podcast Settings**) and **RSS Enabled for This Show** are both on. If RSS is disabled, the panel explains whether the global or show switch is off.

## RSS Readiness

Side panel checklist (collapsed by default). Does not block saving. Shows a warning when RSS is enabled but required items are missing.

## Episodes panel

Lists episodes assigned via **Parent Podcast Show** on each episode. Use **Add New Episode** to create an episode with the show pre-selected.

## Podcast Categories

Taxonomy `podcast_category` for internal site organization (separate from Podcast App Category).

## Podcasts Overview

URL: https://www.mediablaster.io/docs/podcasts
Category: Podcasts
Summary: Enable Podcast Shows and Episodes, public pages, RSS feeds, and REST API output.

# Podcasts Overview

MediaBlaster podcasts use two custom post types:

- **Podcast Shows** (`podcast_show`) — a show container (e.g. *Unexplained History*)
- **Podcast Episodes** (`podcast_episode`) — individual episodes linked to one show

## Enable Podcasts

**MediaBlaster → General Settings → Enable Podcasts**

This master toggle registers both post types, metadata, RSS, public templates, and REST endpoints. Save and reload wp-admin after enabling.

All other podcast options live on the **[Podcast Settings](podcast-settings.md)** tab (public pages, RSS bases, premium teasers when subscriptions are enabled).

## Public pages

When **Enable Podcast Public Pages** is on (Podcast Settings tab):

- Show URL: `/podcasts/{show-slug}/` (base is customizable)
- Episode URL: `/podcasts/{show-slug}/{episode-slug}/`

Disable public pages for headless/API-only setups. Admin and REST remain available.

## RSS feeds

Per-show RSS feeds require:

1. **Enable Podcasts** (General Settings)
2. **Enable Podcast RSS Feeds** ([Podcast Settings](podcast-settings.md))
3. **RSS Enabled for This Show** on the show edit screen
4. Each included episode must have a **valid media enclosure** (uploaded audio/video or direct file URL)

Default feed URL: `/podcast-feed/{show-slug}/`

Only **published, free** episodes with valid enclosures appear as `<item>` entries. Premium episodes are excluded.

If the feed loads but lists no episodes, open the episode and add **Episode Media** — see [Podcast RSS](podcast-rss.md#troubleshooting-empty-feeds).

## Premium episodes

When subscriptions are enabled (`WPST_SUBSCRIPTIONS_ENABLED` in `wp-config.php`), episodes can be marked **Premium** and **Podcast Settings** exposes teaser options.

Premium episodes:

- Are excluded from public RSS
- Do not expose media URLs on public pages or unauthenticated REST
- Can appear as locked teaser cards when **Show Premium Episode Teasers** is enabled

Without subscriptions enabled, the Access Level field remains on episodes for future use; premium-specific Podcast Settings are hidden.

## REST API

Canonical podcast API: `/wp-json/mediablaster/v3/podcasts` — see [REST API — Podcasts](rest-api-podcasts.md).

## v1 exclusions

- No private/tokenized podcast feeds
- No subscription paywall enforcement on RSS yet (premium episodes are excluded, not gated in-feed)
- No import tools yet
- No Media RSS namespace yet
- No transcript RSS namespace yet
- No cloud uploader yet

Public episode pages and embeds use the [Podcast Audio Player](audio-player.md) (shortcode, block, Elementor, and default template).

See also: [Podcast Settings](podcast-settings.md), [Podcast Shows](podcast-shows.md), [Podcast Episodes](podcast-episodes.md), [Podcast RSS](podcast-rss.md), [Podcast Audio Player](audio-player.md).

## Content API and Fields

URL: https://www.mediablaster.io/docs/rest-api-content
Category: REST API
Summary: List, create, update, and delete MediaBlaster content with clean JSON field names.

# Content API and Fields

The content API manages Movies, Videos, Episodes, and Series using normalized JSON. Internal storage still uses `rovidx_smarttv_*` and `rovidx_smart_tv_*` meta keys; the REST layer maps those automatically.

## Endpoints

### Unified routes

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/content` | Paginated collection |
| POST | `/content` | Create (requires `type` in body) |
| GET | `/content/{id}` | Single item |
| PATCH | `/content/{id}` | Partial update |
| DELETE | `/content/{id}` | Trash (or permanent with `?force=true`) |

### Type-specific aliases

Same behavior as `/content`, with `type` fixed by the URL:

| Type | List/create | Item |
|------|-------------|------|
| movies | `GET`, `POST` `/movies` | `GET`, `PATCH`, `DELETE` `/movies/{id}` |
| videos | `/videos` | `/videos/{id}` |
| episodes | `/episodes` | `/episodes/{id}` |
| series | `/series` | `/series/{id}` |

`POST /movies` creates a movie even if `type` is omitted from the JSON body.

If `{id}` exists but belongs to another post type, the API returns **404** `mediablaster_not_found`.

## List collection — query parameters

`GET /content` (or `GET /movies`, etc.)

| Parameter | Description |
|-----------|-------------|
| `type` | Filter: `movies`, `videos`, `episodes`, `series` |
| `status` | `publish`, `draft`, `pending`, `private`, or `any` (editors only) |
| `search` | WordPress search (`s`) |
| `genre` | Filter by genre meta |
| `tag` | Post tag slug or name |
| `series_id` | Episodes in a series playlist (`rovidx_smarttv_playlist`) |
| `page` | Page number (default `1`) |
| `per_page` | Items per page (default `20`, max `100`) |
| `orderby` | `date`, `modified`, `title`, `menu_order`, `rand` |
| `order` | `ASC` or `DESC` |
| `include_locked` | `true` to include items hidden with “hide completely” access |

**Public default:** only `publish` status. Logged-in users with `edit_posts` may request drafts or `status=any`.

### Collection response

```json
{
  "items": [ { "...content object..." } ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 124,
    "total_pages": 7
  }
}
```

## Create and update

### Defaults

- New content defaults to **`draft`**.
- Sending `"status": "publish"` requires `publish_posts` (or equivalent); otherwise **403**.
- **PATCH** only updates fields present in the body; omitted nested keys are not cleared.

### Minimal create example

`POST /wp-json/mediablaster/v3/movies`

```json
{
  "title": "REST Test Movie",
  "description": "Long description.",
  "excerpt": "Short description.",
  "media": {
    "url": "https://cdn.example.com/video.m3u8",
    "duration": 3600,
    "format": "HLS",
    "quality": "FHD"
  },
  "taxonomy": {
    "genres": ["documentary"],
    "rating": "PG",
    "tags": ["History", "Featured"]
  },
  "vimeo": {
    "source_url": "https://vimeo.com/123456789"
  }
}
```

### Partial update example

`PATCH /wp-json/mediablaster/v3/movies/123`

```json
{
  "title": "Updated Title",
  "media": {
    "quality": "UHD"
  }
}
```

Only `title` and `media.quality` change; existing URL and duration remain.

## Delete

`DELETE /content/{id}`

- Default: move to **trash** (`trashed: true`).
- `DELETE /content/{id}?force=true` — permanent delete (requires elevated delete capability).

Response includes `deleted`, `trashed`, and `previous` (serialized snapshot).

## Content object (response shape)

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | WordPress post ID |
| `type` | string | Post type slug |
| `status` | string | `draft`, `publish`, `pending`, `private` |
| `slug` | string | Post name |
| `title` | string | Post title |
| `description` | string | `post_content` |
| `excerpt` | string | `post_excerpt` |
| `created_at` | string | ISO 8601 (GMT) |
| `updated_at` | string | ISO 8601 (GMT) |
| `thumbnail` | object | `{ "id", "url" }` |
| `media` | object | See below |
| `taxonomy` | object | `tags`, `genres`, `rating` |
| `series` | object | Series linkage (episodes) or series meta |
| `captions` | array | Caption tracks |
| `trickplay` | array | Trickplay/BIF files |
| `ads` | object | Ad breaks |
| `availability` | object | Start/end dates |
| `access` | object | Subscription lock state |
| `vimeo` | object | `source_url` |
| `links` | object | `self`, `edit` (if allowed) |

### `media`

| Field | Allowed values | Notes |
|-------|----------------|-------|
| `url` | URI | Playback URL; `null` if user lacks access |
| `duration` | integer (seconds) | Accepts `hh:mm:ss` on write |
| `format` | `MP4`, `MOV`, `M4V`, `HLS`, `SMOOTH`, `DASH` | |
| `quality` | `SD`, `HD`, `FHD`, `UHD` | |

### `taxonomy`

| Field | Description |
|-------|-------------|
| `tags` | Post tag names |
| `genres` | Genre keys (multicheck values) |
| `rating` | Parental rating string |

### `series` (episodes)

| Field | Description |
|-------|-------------|
| `series_id` | Parent series post ID (derived from playlist membership) |
| `season_number` | Season number |
| `episode_number` | Episode number |

### `series` (series post type)

Additional fields on `type: series` responses: `type`, `release_date`, `playlist`, `thumbnail`, `thumbnail_id`, `genres`.

### `captions[]` response fields

| Field | Description |
|-------|-------------|
| `url` | Caption file URL |
| `language` | Language code |
| `type` | e.g. `CLOSED_CAPTION`, `SUBTITLE` |

### `trickplay[]` response fields

| Field | Description |
|-------|-------------|
| `url` | BIF or trickplay file URL |
| `quality` | Quality label |

### `ads` response fields

| Field | Description |
|-------|-------------|
| `ad_breaks` | Array of break positions (seconds) |
| `custom_midroll_timer` | Custom midroll offset or `null` |

### `availability` response fields

| Field | Description |
|-------|-------------|
| `start_date` | Availability start or `null` |
| `end_date` | Availability end or `null` |

### `access`

Present when subscriptions are enabled:

| Field | Description |
|-------|-------------|
| `is_locked` | Premium/locked for current user |
| `user_can_access` | Whether playback URL may be shown |
| `required_tier` | Tier object or `null` |
| `required_access_group` | Access group object or `null` |

### `vimeo` response fields

| Field | Description |
|-------|-------------|
| `source_url` | Vimeo page URL (`rovidx_smart_tv_vm_pro_url`) |

### `links`

| Field | Description |
|-------|-------------|
| `self` | REST URL for this item |
| `edit` | wp-admin edit link (only if user can edit) |

## Request body field reference

Use these keys in **POST** and **PATCH** bodies (not raw meta names).

### Top-level

| API field | Required | Notes |
|-----------|----------|-------|
| `type` | On `POST /content` | One of four content types |
| `status` | No | Default `draft` |
| `title` | On create | |
| `description` | No | HTML allowed (sanitized) |
| `excerpt` | No | |
| `slug` | No | Post name |

### `media` object

| API field | Internal meta key |
|-----------|-------------------|
| `url` | `rovidx_smarttv_URL` |
| `duration` | `rovidx_smarttv_Duration` |
| `format` | `rovidx_smarttv_format` |
| `quality` | `rovidx_smarttv_quality` |

### `taxonomy` object

| API field | Storage |
|-----------|---------|
| `genres` | `rovidx_smarttv_genres` |
| `rating` | `rovidx_smarttv_rating` |
| `tags` | WordPress post tags |

### `series` object (episodes)

| API field | Internal meta key |
|-----------|-------------------|
| `season_number` | `rovidx_smarttv_se_no` |
| `episode_number` | `rovidx_smarttv_ep_no` |

### `series` object (series CPT)

| API field | Internal meta key |
|-----------|-------------------|
| `type` | `rovidx_smarttv_series_type` |
| `release_date` | `rovidx_smarttv_series_release_date` |
| `playlist` | `rovidx_smarttv_playlist` (array of post IDs) |
| `thumbnail` | `rovidx_smarttv_series_thumb` |
| `thumbnail_id` | `rovidx_smarttv_series_thumb_id` |
| `genres` | `rovidx_smarttv_series_genres` |

### `captions[]` internal keys

| API field | Internal key |
|-----------|--------------|
| `url` | `rovidx_smarttv_cc_uri` |
| `language` | `rovidx_smarttv_cc_lang` |
| `type` | `rovidx_smarttv_cc_type` |

Stored as CMB2 group `rovidx_smarttv_cc`.

### `trickplay[]` internal keys

| API field | Internal key |
|-----------|--------------|
| `url` | `rovidx_smarttv_bif_uri` |
| `quality` | `rovidx_smarttv_bif_def` |

Stored as group `rovidx_smarttv_bif`.

### `ads` internal keys

| API field | Internal meta key |
|-----------|-------------------|
| `ad_breaks` | `rovidx_smarttv_ad_breaks` |
| `custom_midroll_timer` | `rovidx_smarttv_custom_midroll_timer` |

### `availability` internal keys

| API field | Internal meta key |
|-----------|-------------------|
| `start_date` | `rovidx_smarttv_start_date` |
| `end_date` | `rovidx_smarttv_end_date` |

### `vimeo` internal keys

| API field | Internal meta key |
|-----------|-------------------|
| `source_url` | `rovidx_smart_tv_vm_pro_url` |

### `thumbnail`

| API field | Action |
|-----------|--------|
| `id` | Sets featured image attachment ID |

## Related guides

- [REST API Overview](rest-api-overview.md)
- [Video Data metabox](metabox-video-data.md) (admin UI for the same fields)
- [Vimeo REST API](rest-api-vimeo.md)
- [Metabox Subscription Access](metabox-subscription-access.md)

## REST API — App Config

URL: https://www.mediablaster.io/docs/rest-api-app-config
Category: REST API
Status: available
Product: Roku Launch Kit
Summary: Public platform app configuration feed for Roku and future TV/mobile clients.

# REST API — App Config

Platform-specific **behavior, branding, layout, and feature visibility** for connected apps.

## Endpoint

```
GET /wp-json/mediablaster/v3/config?platform=roku
```

| Property | Value |
|----------|-------|
| Auth | None (public) |
| Method | GET |
| Query `platform` | Default `roku`; currently only `roku` is supported |

Discovery index includes `links.config` pointing to this URL.

## What this endpoint is (and is not)

**Is:**

- Remote source of truth for user-configurable app settings managed under **MediaBlaster → App Config**
- Branding colors, labels, navigation feature flags, home layout, boot behavior, and similar client settings

**Is not:**

- API discovery — the client must already know the WordPress base URL
- Subscription or Stripe configuration — use `GET /app/config` instead (requires subscriptions REST enabled)
- A place for secrets — never include API keys, tokens, or `apiBaseUrl` / `apiOrigin`

## Query parameters

| Param | Default | Description |
|-------|---------|-------------|
| `platform` | `roku` | Platform slug (`roku` only in v1) |

Invalid platform:

```json
{
  "code": "mediablaster_invalid_platform",
  "message": "Unsupported platform.",
  "data": { "status": 400 }
}
```

## Response overview (Roku)

Top-level fields include:

| Field | Description |
|-------|-------------|
| `platform` | `roku` |
| `schemaVersion` | Config schema version (e.g. `1.0`) |
| `appName` | Display name |
| `debugMode` | Diagnostic logging toggle |
| `enableSubscriptions` | App-level subscriptions UI toggle |
| `enableVod`, `enableMovies`, `enableSeries`, … | Content availability flags |
| `brandColor`, `accentOrange`, … | Branding colors (hex) |
| `heroFallbackImage`, `posterFallbackImage` | Roku asset paths |
| `supportUrl`, `privacyUrl` | Public legal/help links |
| `sidebarEnabled` | Sidebar visibility |
| `features` | Navigation destination flags (`home`, `movies`, `series`, …) |
| `labels` | Custom UI strings |
| `layout` | Home screen layout flags |
| `sidebar` | `expandedWidth`, `collapsedWidth` |
| `homeTagRows` | Tag row settings |
| `homeRows` | Always `[]` in v1 |
| `boot` | `requireDiscovery`, `loadFeaturedOnStart` |
| `meta.generatedAt` | ISO 8601 timestamp (UTC) |

Values merge saved WordPress options over plugin defaults. Unsaved installs still return sensible defaults.

## Admin configuration

Manage values at **MediaBlaster → App Config → App Settings**. See [App Config](app-config.md).

Option key: `mediablaster_app_config`

## Compare with `/app/config`

| Route | Purpose | Auth | Requires subscriptions |
|-------|---------|------|------------------------|
| `GET /config?platform=roku` | Platform app UI/behavior config | Public | No |
| `GET /app/config` | Stripe keys, tiers, auth flags | Public when REST on | Yes (+ REST enabled) |

## Verification

Open `/wp-json/mediablaster/v3/config?platform=roku` in a browser to confirm the endpoint returns your saved settings.

## Related guides

- [App Config](app-config.md)
- [REST API Overview](rest-api-overview.md)
- [Subscriptions and Apps API](rest-api-subscriptions.md) — `/app/config`

## REST API — Podcasts

URL: https://www.mediablaster.io/docs/rest-api-podcasts
Category: REST API
Summary: mediablaster/v3 podcast show and episode endpoints with public-safe premium stripping.

# REST API — Podcasts

Namespace: `/wp-json/mediablaster/v3`

Available when **Enable Podcasts** is on. Discovery index includes `features.podcasts` and `links.podcasts`.

## Endpoints

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/podcasts` | List podcast shows |
| GET | `/podcasts/{show_id}` | Single show with episode counts |
| GET | `/podcasts/{show_id}/episodes` | Episodes for a show (filters, pagination) |
| GET | `/podcast-episodes/{episode_id}` | Single episode with parent show summary |

## Query parameters

**GET /podcasts**

- `include_episodes` (bool, default false)
- `episodes_per_show` (int, default 3)
- `episode_preview` (`latest` \| `featured`, default `latest`)
- `page`, `per_page`

**GET /podcasts/{show_id}/episodes**

- `featured` (bool)
- `access` (`free` \| `premium`)
- `type` (`full` \| `trailer` \| `bonus`)
- `rss` (`included` \| `excluded` \| `missing_enclosure`)
- `page`, `per_page`

## Public vs authenticated

Unauthenticated requests return published public-safe content only. Premium episodes do not expose media URLs, full transcripts, or RSS enclosures publicly.

Episode `rss_status` values: `included`, `excluded`, `missing_enclosure` — useful when debugging empty RSS feeds.

Users with `edit_posts` receive authenticated context (drafts/private/premium metadata), still without exposing premium media URLs on anonymous requests.

## Normalized objects

Shows include id, slug, title, url, rss_url, artwork, subtitle, description, host, credits, owner fields, language, copyright, app_category, explicit, rss settings, distribution_links, categories, tags, and episode_counts.

Episodes include id, slug, title, url, podcast_show summary, artwork, show_notes, publish_date, type/season/number, duration, explicit, access, featured, rss_status, canonical_audio/video (when allowed), transcript, chapters, guests, and tags.

## REST API Overview

URL: https://www.mediablaster.io/docs/rest-api-overview
Category: REST API
Summary: MediaBlaster v3 REST namespace, discovery, schema, errors, and permissions.

# REST API Overview

MediaBlaster 3.0 exposes a single custom WordPress REST namespace for apps, agents, and integrations.

## Base URL

All routes live under:

```
https://YOUR-SITE.com/wp-json/mediablaster/v3
```

Legacy namespaces **`tv/roku`** and **`wpst/v1`** are not registered in 3.0.0.

## Discovery

`GET /wp-json/mediablaster/v3`

Public. Returns API metadata and links to major endpoints.

Example response fields:

| Field | Description |
|-------|-------------|
| `name` | Product name (MediaBlaster) |
| `version` | Plugin version |
| `namespace` | `mediablaster/v3` |
| `enabled_post_types` | Active content types on this site |
| `features` | `vimeo`, `subscriptions`, `agent_tools` flags |
| `links` | Absolute URLs to schema, content, type routes, platform config (`config`), Vimeo, auth |

Use this endpoint to probe capabilities before building a client.

## Schema

Describe the public field model (not raw WordPress meta keys).

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/schema` | Schema for all supported types |
| GET | `/schema/{type}` | Schema for one type (`movies`, `videos`, `episodes`, `series`) |

Each schema object includes `type`, `label`, `supports`, and a `fields` map with types, enums, and required flags.

See [Content API and Fields](rest-api-content.md) for how schema fields map to request and response bodies.

## Error responses

Errors use WordPress `WP_Error` JSON:

```json
{
  "code": "mediablaster_not_found",
  "message": "Content not found.",
  "data": { "status": 404 }
}
```

Common codes:

| Code | HTTP | Meaning |
|------|------|---------|
| `mediablaster_invalid_type` | 400 | Unknown or disallowed post type |
| `mediablaster_invalid_payload` | 400 | Validation failed |
| `mediablaster_not_found` | 404 | Post missing or wrong type for route |
| `mediablaster_forbidden` | 403 | Capability or publish permission denied |
| `mediablaster_vimeo_not_configured` | 400 | Vimeo integration off or not connected |
| `mediablaster_vimeo_sync_failed` | 500 | Vimeo API or sync error |
| `mediablaster_invalid_platform` | 400 | Unsupported `platform` on `/config` |

## Permissions (summary)

| Action | Requirement |
|--------|-------------|
| Read published content | Public (subject to subscription access rules) |
| Read drafts/private | User with `edit_posts` and appropriate query |
| Create content | `edit_posts` |
| Update content | `edit_post` on that post |
| Delete / trash | `delete_post`; permanent delete needs `force=true` and strong delete cap |
| Vimeo import/sync | `edit_posts` + Vimeo enabled |
| Admin stats | `manage_options` |
| Auth / payments | See [Subscriptions and Apps API](rest-api-subscriptions.md) |

Locked premium content may omit `media.url` for users without access while other metadata remains visible.

## Endpoint index

### Content (always available)

| Method | Route |
|--------|-------|
| GET, POST | `/content` |
| GET, PATCH, DELETE | `/content/{id}` |
| GET, POST | `/movies`, `/videos`, `/episodes`, `/series` |
| GET, PATCH, DELETE | `/{type}/{id}` |

Type routes are aliases of `/content` with `type` implied by the path.

### App Config (always available)

| Method | Route |
|--------|-------|
| GET | `/config?platform=roku` |

Public platform app settings (branding, navigation, layout, labels). Managed under **MediaBlaster → App Config → App Settings**. Distinct from subscription `GET /app/config`.

See [REST API — App Config](rest-api-app-config.md).

### Vimeo (requires **Enable Vimeo Integration**)

| Method | Route |
|--------|-------|
| GET | `/vimeo/status` |
| POST | `/vimeo/import` |
| POST | `/vimeo/sync/{post_id}` |

See [Vimeo REST API](rest-api-vimeo.md).

### Subscriptions and apps (requires `WPST_SUBSCRIPTIONS_ENABLED` + REST enabled)

| Method | Route |
|--------|-------|
| GET | `/me` |
| GET | `/subscription/status` |
| GET | `/subscription/tiers` |
| GET | `/app/config` |
| POST | `/auth/register`, `/auth/login`, `/auth/logout`, `/auth/refresh` |
| POST | `/payments/stripe/create-checkout-session` |
| POST | `/payments/stripe/create-portal-session` |
| GET | `/payments/stripe/checkout-session` |
| POST | `/payments/stripe/webhook` (and other provider webhooks) |
| GET | `/stats/content`, `/stats/subscriptions`, `/stats/revenue` |

See [Subscriptions and Apps API](rest-api-subscriptions.md).

## Authentication for write requests

- **WordPress session** — cookie auth while logged into wp-admin works for same-origin tools.
- **Application Passwords** — standard WordPress application passwords for server-to-server writes.
- **Bearer tokens** — when subscriptions REST is enabled, `POST /auth/login` returns a token; send `Authorization: Bearer {token}` on subsequent requests.

## Related guides

- [Content API and Fields](rest-api-content.md)
- [REST API — App Config](rest-api-app-config.md)
- [Vimeo REST API](rest-api-vimeo.md)
- [Subscriptions and Apps API](rest-api-subscriptions.md)
- [Subscriptions API and Auth](subscriptions-api-auth.md) (admin settings)
- [Import and Export](import-export.md)

## Subscriptions and Apps API

URL: https://www.mediablaster.io/docs/rest-api-subscriptions
Category: REST API
Summary: Auth tokens, viewer profile, tiers, Stripe checkout, webhooks, and admin stats.

# Subscriptions and Apps API

These routes extend `/wp-json/mediablaster/v3` when:

1. `WPST_SUBSCRIPTIONS_ENABLED` is `true` in `wp-config.php`, and  
2. **Enable REST/API access** is on under **MediaBlaster → Subscriptions → General**.

Configure token and login options under **Subscriptions → API/Auth**. See [Subscriptions API and Auth](subscriptions-api-auth.md) for admin settings.

## Authentication

Send bearer tokens on protected routes:

```
Authorization: Bearer {token}
```

Obtain a token with `POST /auth/login` (when enabled). WordPress cookie sessions also work for same-site browser apps on routes that allow it.

## Auth endpoints

| Method | Route | Auth | Description |
|--------|-------|------|-------------|
| POST | `/auth/register` | Public | Create account (if headless registration enabled) |
| POST | `/auth/login` | Public | Email/password login; returns token |
| POST | `/auth/logout` | Bearer | Revoke current token |
| POST | `/auth/refresh` | Bearer | Issue new token (if refresh enabled) |

### Login request

```json
{
  "username": "viewer@example.com",
  "password": "your-password",
  "device_name": "iOS App",
  "device_type": "mobile"
}
```

Successful login returns `token`, `expires_at`, `user`, and subscription/entitlement summaries.

## Viewer profile

### `GET /me`

Public route; returns authentication state without exposing sensitive token details.

**Logged out:**

```json
{
  "authenticated": false,
  "user": null
}
```

**Logged in:**

```json
{
  "authenticated": true,
  "user": {
    "id": 1,
    "name": "Display Name",
    "email": "user@example.com"
  },
  "subscription": {
    "active": true,
    "tier": {
      "id": 2,
      "name": "Premium",
      "slug": "premium"
    }
  }
}
```

Email is included only for the authenticated user making the request.

### `GET /subscription/status`

Requires authentication (session or Bearer).

Returns subscription summary for the current user (active state, tier, entitlements). Use for account screens after login.

### `GET /subscription/tiers`

Public when REST is enabled. Lists active subscription tiers with pricing and `stripe_available` flags.

## App configuration

`GET /app/config`

Public when subscriptions REST is enabled. Returns **subscription and payment** client configuration for headless apps (Stripe publishable key, tiers, auth flags).

**Not the same as** `GET /config?platform=roku` — that route serves **platform app UI/behavior** (branding, navigation, layout) from **MediaBlaster → App Config** and is always public. See [REST API — App Config](rest-api-app-config.md).

`/app/config` response fields:

| Field | Description |
|-------|-------------|
| `site_name` | Blog name |
| `subscriptions_enabled` | Module active |
| `registration_enabled` | Headless register allowed |
| `login_enabled` | Login endpoint allowed |
| `payment_providers` | Enabled provider metadata |
| `stripe` | Publishable key, mode, checkout/portal endpoint URLs |
| `tiers` | Active tiers (public fields) |
| `frontend_mode` | Configured frontend mode |
| `rest_api_enabled` | REST gate |
| `api_namespace` | `mediablaster/v3` |
| `feature_flags` | Token refresh, device registration |

Secret keys are never included.

Stripe endpoint URLs in this payload point to `mediablaster/v3` paths.

## Stripe payments

Requires authenticated user (session or Bearer) unless noted.

| Method | Route | Description |
|--------|-------|-------------|
| POST | `/payments/stripe/create-checkout-session` | Start Stripe Checkout for a `tier_id` |
| POST | `/payments/stripe/create-portal-session` | Stripe Customer Portal for billing management |
| GET | `/payments/stripe/checkout-session` | Lookup session by `session_id` query param |
| POST | `/payments/stripe/webhook` | Stripe webhooks (signature verified; no login) |

Configure the Stripe Dashboard webhook URL to:

```
https://YOUR-SITE.com/wp-json/mediablaster/v3/payments/stripe/webhook
```

Other providers (PayPal, Apple, Google, Amazon) use `POST /payments/{provider}/webhook` or receipt routes as configured in admin.

See [Stripe Checkout Setup](stripe-checkout-setup.md) for Dashboard and tier Price ID setup.

## Admin statistics

Requires `manage_options`.

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/stats/content` | Post counts by type and status |
| GET | `/stats/subscriptions` | Subscription totals when tables exist |
| GET | `/stats/revenue` | Placeholder (`available: false`) until revenue analytics ship |

### Content stats example

```json
{
  "counts": {
    "movies": {
      "publish": 10,
      "draft": 2,
      "pending": 0,
      "private": 0
    },
    "videos": { "publish": 5, "draft": 0, "pending": 0, "private": 0 }
  }
}
```

Revenue stats do not return fabricated amounts.

## Content access and REST

Premium rules apply to [Content API](rest-api-content.md) responses:

- `access.is_locked` and `access.user_can_access` describe entitlement state.
- `media.url` may be `null` when the viewer cannot play the item.
- Items with “hide completely” behavior may be omitted from lists unless `include_locked=true`.

Configure per-post access in the [Subscription Access metabox](metabox-subscription-access.md).

## Related guides

- [REST API Overview](rest-api-overview.md)
- [Content API and Fields](rest-api-content.md)
- [Subscriptions API and Auth](subscriptions-api-auth.md)
- [Stripe Checkout Setup](stripe-checkout-setup.md)

## Vimeo REST API

URL: https://www.mediablaster.io/docs/rest-api-vimeo
Category: REST API
Summary: Check Vimeo connection status and import or sync videos via REST.

# Vimeo REST API

Vimeo REST routes require **Enable Vimeo Integration** on **MediaBlaster → General Settings**, plus a connected OAuth token under **Integrations**.

Base path: `/wp-json/mediablaster/v3/vimeo/`

All Vimeo write routes require `edit_posts`.

## Status

`GET /vimeo/status`

Returns whether credentials and an access token are configured.

**Configured and connected:**

```json
{
  "configured": true,
  "authenticated": true
}
```

**Not configured:**

```json
{
  "configured": false,
  "authenticated": false,
  "message": "Vimeo API credentials are not configured."
}
```

Use this before building import UIs so clients can show setup instructions.

## Import from Vimeo URL

`POST /vimeo/import`

Creates a new content post from a Vimeo video and populates MediaBlaster meta from the Vimeo API.

### Request body

| Field | Required | Description |
|-------|----------|-------------|
| `vimeo_url` | Yes | Full Vimeo URL (e.g. `https://vimeo.com/123456789`) |
| `type` | Yes | `movies`, `videos`, or `episodes` (not `series`) |
| `status` | No | Default `draft`; `publish` requires publish capability |

Example:

```json
{
  "vimeo_url": "https://vimeo.com/123456789",
  "type": "movies",
  "status": "draft"
}
```

### Create behavior

- Fetches video metadata from Vimeo (`/me/videos/{id}`).
- Creates a WordPress post of the requested type.
- Sets `rovidx_smart_tv_vm_pro_url` from the Vimeo link.
- Sets HLS URL, duration, format (`HLS`), quality, title/description when import options allow.
- Attaches featured image from Vimeo thumbnails when available.
- Imports Vimeo tags to post tags when present.

Response: full [content object](rest-api-content.md) for the new post.

## Sync existing post

`POST /vimeo/sync/{post_id}`

Refreshes an existing post from its stored Vimeo URL.

### Requirements

- Post must exist and be a supported content type.
- Caller must be able to `edit_post` for that ID.
- Post meta `rovidx_smart_tv_vm_pro_url` must contain a valid Vimeo URL.

### Refresh behavior

- Re-fetches Vimeo video data.
- Updates `rovidx_smarttv_URL`, duration, format, quality, and optional title/description per **Vimeo Settings** import toggles.
- Updates featured image when a thumbnail is available.

Response: full updated content object.

Errors:

| Code | When |
|------|------|
| `mediablaster_not_found` | Invalid post |
| `mediablaster_forbidden` | Cannot edit post |
| `mediablaster_invalid_payload` | Missing Vimeo URL on post |
| `mediablaster_vimeo_not_configured` | Integration disabled |
| `mediablaster_vimeo_sync_failed` | Vimeo API or processing error |

## Admin alternatives

The same Vimeo logic is available in wp-admin without REST:

- **Load Video Data** on the post editor ([Vimeo metabox](metabox-vimeo-import.md))
- **Vimeo Mass Import** ([Mass Import guide](vimeo-mass-import.md))

REST is intended for agents, headless tools, and automated pipelines.

## Related guides

- [REST API Overview](rest-api-overview.md)
- [Content API and Fields](rest-api-content.md)
- [Integrations — Vimeo OAuth](integrations-vimeo-oauth.md)
- [Vimeo Settings](vimeo-settings.md)

## Access Groups

URL: https://www.mediablaster.io/docs/subscriptions-access-groups
Category: Subscriptions
Summary: Bundle content into groups and assign them to subscription tiers.

# Access Groups

**Location:** MediaBlaster → Subscriptions → **Access Groups** tab

Access groups bundle content for entitlement checks. Tiers link to groups — subscribers on a tier can watch content tagged with any of that tier's groups.

## Creating an access group

1. Open **Access Groups** and click **Add New**.
2. Enter **Name** and optional **Description**.
3. **Slug** is derived from the name if left empty.
4. Save and confirm the success notice.

If save fails silently, subscription database tables may be missing — reload any wp-admin page to trigger automatic repair, then try again.

## Linking groups to tiers

Edit a tier under [Tiers](subscriptions-tiers.md) and assign one or more access groups. A subscriber on that tier receives access to all videos requiring those groups (or the tier itself).

## Per-video overrides

On individual posts, the [Subscription Access metabox](metabox-subscription-access.md) can require a specific access group or tier beyond defaults.

## Use cases

| Group | Example |
|-------|---------|
| **Premium catalog** | All movies and episodes marked "subscriber" |
| **Sports pack** | Videos tagged with sports access group |
| **Early access** | Tier-specific group for pre-release content |

## Related guides

- [Subscription Tiers](subscriptions-tiers.md)
- [Subscription Access metabox](metabox-subscription-access.md)

## Payment Providers

URL: https://www.mediablaster.io/docs/subscriptions-payment-providers
Category: Subscriptions
Summary: Connect Stripe and configure billing keys, webhooks, and redirect URLs.

# Payment Providers

**Location:** MediaBlaster → Subscriptions → **Payment Providers** tab

Connect billing providers to sell subscriptions. **Stripe Web Checkout (Phase 2A)** is fully supported. PayPal, Apple, Google, and Amazon sections are scaffolding for future phases.

## Stripe (recommended)

| Setting | Description |
|---------|-------------|
| **Enable Stripe** | Master toggle for checkout buttons, webhooks, and billing portal. |
| **Mode** | **Test** or **Live** — controls which API keys and tier Price IDs are used. |
| **Publishable key** | `pk_test_...` or `pk_live_...` from Stripe Dashboard. |
| **Secret key** | `sk_test_...` or `sk_live_...` — masked after save; leave blank to keep existing value. |
| **Webhook signing secret** | From Stripe Dashboard webhook endpoint — masked after save. |
| **Checkout success URL** | Redirect after payment; may include `{CHECKOUT_SESSION_ID}`. |
| **Checkout cancel URL** | Redirect when user abandons checkout. |
| **Customer portal return URL** | Return URL after Manage Billing in Stripe Portal. |
| **Default currency** | e.g. USD — used when tier currency is empty. |
| **Debug logging** | Redacted Stripe logs to PHP error log. |

The admin page displays your **webhook endpoint URL**:

```
https://YOUR-SITE/wp-json/mediablaster/v3/payments/stripe/webhook
```

Copy this into Stripe Dashboard → Developers → Webhooks for the matching test or live mode.

## Legacy tier → Price ID mapping

A repeatable mapping group exists for older configurations. Prefer setting **Stripe Price IDs** directly on each tier under [Tiers](subscriptions-tiers.md).

## Other providers

PayPal, Apple In-App Purchase, Google Play, and Amazon IAP sections allow enabling flags and placeholder credential fields. Checkout flows for these providers are **not yet implemented** — use Stripe for web subscriptions today.

## Full Stripe setup

See the dedicated [Stripe Checkout Setup](stripe-checkout-setup.md) guide for Dashboard steps, webhook events, test cards, and troubleshooting.

## Security

Secret keys and webhook secrets never appear in full in admin HTML after saving. They are not exposed via public REST routes. Only administrators can change payment settings.

## Stripe Checkout Setup

URL: https://www.mediablaster.io/docs/stripe-checkout-setup
Category: Subscriptions
Summary: Complete Stripe Dashboard and WordPress setup for hosted checkout and webhooks.

# Stripe Checkout Setup

Complete guide to accepting subscription payments with Stripe Web Checkout (Phase 2A).

## Prerequisites

- `WPST_SUBSCRIPTIONS_ENABLED` set to `true` in `wp-config.php`
- **Enable REST/API access** under Subscriptions → General
- HTTPS recommended for production
- Stripe account with Products and recurring Prices for each tier

## Stripe Dashboard setup

### 1. API keys

In Stripe Dashboard → **Developers → API keys**:

- Copy **test** publishable and secret keys into MediaBlaster → Subscriptions → **Payment Providers**
- When ready for production, repeat with **live** keys and switch **Mode** to Live

### 2. Webhook endpoint

Add a webhook in Stripe Dashboard pointing to:

```
https://YOUR-SITE/wp-json/mediablaster/v3/payments/stripe/webhook
```

Subscribe to these events (test and live each need their own endpoint or secret):

- `checkout.session.completed`
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`
- `invoice.payment_failed`

Copy the **signing secret** into the matching test/live webhook secret field in MediaBlaster.

### 3. Products and Prices

Create a Stripe Product and recurring Price for each MediaBlaster tier. Copy each **Price ID** (`price_...`) into [Subscription Tiers](subscriptions-tiers.md) for the correct test or live mode.

Trial days configured on a tier are sent to Stripe as `trial_period_days` on checkout.

## WordPress configuration

| Setting | Example |
|---------|---------|
| Checkout success URL | `https://yoursite.com/subscribe-success/?session_id={CHECKOUT_SESSION_ID}` |
| Checkout cancel URL | `https://yoursite.com/subscribe/` |
| Portal return URL | `https://yoursite.com/account/` |

Create WordPress pages:

```
[wpst_subscribe]
[wpst_account]
```

See [Shortcodes](shortcodes.md) for single-tier checkout with `[wpst_stripe_checkout]`.

## Checkout flow

1. Logged-in user clicks **Subscribe** on your subscribe page
2. Browser requests a checkout session from MediaBlaster REST API
3. User completes payment on Stripe hosted checkout
4. Stripe redirects to your success URL
5. Webhooks update the internal subscription — premium access applies

## Testing checklist

Use Stripe test card **4242 4242 4242 4242** with any future expiry and CVC.

- [ ] Test keys saved; webhook secret configured
- [ ] Tier has test Price ID mapped
- [ ] Logged-out user sees login prompt on subscribe page
- [ ] Logged-in user reaches Stripe Checkout
- [ ] Success and cancel redirects work
- [ ] Sub Logs show `checkout.session.completed`
- [ ] Subscriber can play premium `[tv-video-player]` content
- [ ] **Manage Billing** opens Stripe Customer Portal on account page

## Troubleshooting

| Symptom | Check |
|---------|-------|
| No Subscribe button | User logged in? Stripe enabled? Tier has Price ID for current mode? |
| Checkout REST error | Subscriptions and REST API enabled? User authenticated? |
| Webhook signature failure | Webhook secret matches current test/live mode |
| Subscription not created | Sub Logs for `unmapped` or `error`; Price ID matches Stripe subscription |
| Manage Billing missing | User needs Stripe customer ID from completed checkout |

## Security

- Webhooks verify Stripe HMAC signatures only — no WordPress login
- Secret keys never appear in public REST or page HTML
- Redirect URLs must be same-site unless filtered for your domain

## Headless apps

`GET /wp-json/mediablaster/v3/app/config` returns public Stripe config (publishable key, endpoints) without secrets. Authenticated apps use `POST /wp-json/mediablaster/v3/payments/stripe/create-checkout-session` with Bearer token.

For REST auth details see [API/Auth settings](subscriptions-api-auth.md).

## Subscribers

URL: https://www.mediablaster.io/docs/subscriptions-subscribers
Category: Subscriptions
Summary: Search users, manage subscriptions manually, and sync from Stripe.

# Subscribers

**Location:** MediaBlaster → Subscriptions → **Subscribers** tab

View and manage viewer subscriptions — search users, assign tiers manually, cancel or expire subscriptions, and sync state from Stripe.

## Finding a subscriber

Use the search field to find users by email, display name, or login. Results show current subscription status, tier, provider, and renewal dates.

## Manual subscription actions

Administrators can:

- **Assign** a tier to a user (creates or updates internal subscription record)
- **Cancel** an active subscription
- **Expire** a subscription immediately for testing or support cases

Manual changes update MediaBlaster's internal entitlement system directly. If the user also has an active Stripe subscription, consider using Stripe Dashboard or **Sync from Stripe** to avoid mismatches.

## Sync from Stripe

When Stripe is enabled and the user has a Stripe customer ID (set after first checkout), click **Sync from Stripe** to pull the latest subscription state from Stripe into MediaBlaster.

Use this when:

- Webhooks were missed during development
- Stripe Dashboard shows a different status than WordPress
- Testing webhook recovery

## Stripe customer IDs

After successful Stripe checkout, customer IDs are stored in user meta (`_wpst_stripe_test_customer_id` or `_wpst_stripe_live_customer_id`). These enable **Manage Billing** on the `[wpst_account]` page.

## Related guides

- [Subscription Tiers](subscriptions-tiers.md)
- [Sub Logs](subscriptions-logs.md)
- [Stripe Checkout Setup](stripe-checkout-setup.md)

## Subscription Logs

URL: https://www.mediablaster.io/docs/subscriptions-logs
Category: Subscriptions
Summary: Audit trail of payment webhooks and subscription provider events.

# Subscription Logs

**Location:** MediaBlaster → Subscriptions → **Sub Logs** tab

Sub Logs record payment provider events — especially Stripe webhooks — for troubleshooting billing and entitlement sync issues.

## What appears in the log

Each row typically includes:

- **Event type** — e.g. `checkout.session.completed`, `customer.subscription.updated`
- **Provider** — Stripe, PayPal, etc.
- **Status** — processed, duplicate, error, unmapped
- **Timestamp** — when the event was received
- **Details** — redacted payload summary or error message

## Common statuses

| Status | Meaning |
|--------|---------|
| **processed** | Webhook handled; internal subscription updated |
| **duplicate** | Same Stripe event ID already processed (safe to ignore) |
| **error** | Handler failed — check message and server logs |
| **unmapped** | Stripe Price ID not linked to any tier |

## Troubleshooting with logs

| Issue | Check logs for |
|-------|----------------|
| User paid but no access | Missing `checkout.session.completed` or `unmapped` price |
| Wrong tier assigned | Price ID mismatch between Stripe and tier editor |
| Webhook not arriving | No recent entries — verify Stripe endpoint URL and signing secret |
| Duplicate events | `duplicate` status confirms idempotent handling |

## Debug logging

Enable **Debug logging** under [Payment Providers](subscriptions-payment-providers.md) for additional redacted Stripe detail in PHP error logs. Disable after diagnosis.

## Related guides

- [Stripe Checkout Setup](stripe-checkout-setup.md)
- [Subscribers](subscriptions-subscribers.md)

## Subscription Tiers

URL: https://www.mediablaster.io/docs/subscriptions-tiers
Category: Subscriptions
Summary: Create subscription plans, pricing, trials, and Stripe Price ID mapping.

# Subscription Tiers

**Location:** MediaBlaster → Subscriptions → **Tiers** tab

Tiers are your subscription plans — e.g. Basic, Premium, Annual. Each tier defines price, billing interval, trial days, linked access groups, and Stripe Price IDs for checkout.

## Creating a tier

1. Open the **Tiers** tab and click **Add New** (or edit an existing row).
2. Fill in:
   - **Name** — display name on `[wpst_subscribe]` and account pages
   - **Slug** — URL-safe identifier (auto-generated from name if empty)
   - **Description** — optional plan summary
   - **Price** and **Currency** — shown to subscribers (Stripe charges use mapped Price IDs)
   - **Billing interval** — month, year, etc.
   - **Trial days** — free trial length; passed to Stripe checkout when configured
   - **Active** — inactive tiers are hidden from subscribe UI
3. Assign **Access Groups** that this tier unlocks.
4. Set **Stripe test Price ID** and **Stripe live Price ID** (`price_...` from Stripe Dashboard) for the modes you use.
5. Save — confirm the success notice and verify the row appears in the list.

## Stripe Price IDs

Each active tier needs a Stripe Price ID matching your current **Mode** (test or live) under [Payment Providers](subscriptions-payment-providers.md).

Without a mapped Price ID, logged-in users will not see a Subscribe button for that tier (admins see a warning on the subscribe page).

Create Products and Prices in Stripe Dashboard, then paste the Price ID into the tier editor.

## Access groups

Link one or more [Access Groups](subscriptions-access-groups.md) to a tier. Subscribers on that tier receive entitlements for all linked groups.

Individual videos can also require a specific tier or group via the [Subscription Access metabox](metabox-subscription-access.md).

## Related guides

- [Stripe Checkout Setup](stripe-checkout-setup.md)
- [Subscribers](subscriptions-subscribers.md) — manual tier assignment

## Subscriptions API and Auth

URL: https://www.mediablaster.io/docs/subscriptions-api-auth
Category: Subscriptions
Summary: REST authentication, bearer tokens, login endpoints, and security options.

# Subscriptions API and Auth

**Location:** MediaBlaster → Subscriptions → **API/Auth** tab

Configure how apps and headless clients authenticate against the MediaBlaster REST API at `/wp-json/mediablaster/v3/`.

## Prerequisites

- `WPST_SUBSCRIPTIONS_ENABLED` set to `true` in `wp-config.php`.
- **Enable REST/API access** on Subscriptions → General.

## Token and login settings

| Setting | Description |
|---------|-------------|
| **Enable app/device API tokens** | Issues Bearer tokens for authenticated API requests. |
| **Token expiry days** | How long access tokens remain valid before refresh. |
| **Allow email/password login endpoint** | `POST /auth/login` for app sign-in. |
| **Allow token refresh endpoint** | `POST /auth/refresh` to renew tokens. |
| **Allow device name registration** | Associates tokens with device labels for admin visibility. |
| **Allow headless registration endpoint** | `POST /auth/register` for app-driven sign-up. |
| **Require verified email before API access** | Blocks API use until WordPress email is verified. |

## Security

| Setting | Description |
|---------|-------------|
| **Require HTTPS for API token login** | Rejects login over plain HTTP in production. |
| **Locked content HTTP status** | Return **403 Forbidden** or **404 Not Found** for unauthorized API content requests. |
| **Log payment payloads (debug)** | Writes redacted payment debug info — use only temporarily. |

An admin warning appears when your site is not served over HTTPS while REST tokens or Stripe checkout are enabled.

## Using the API

Authenticate requests with:

```
Authorization: Bearer {token}
```

Obtain a token via `POST /wp-json/mediablaster/v3/auth/login` with email and password, or register via `/auth/register` when enabled.

Common routes (full detail in [Subscriptions and Apps API](rest-api-subscriptions.md)):

- `GET /me` — authentication state and basic profile
- `GET /subscription/status` — active plan summary (auth required)
- `GET /subscription/tiers` — public tier list
- `GET /app/config` — client-safe Stripe and subscription feature config (not platform app config — see [REST API — App Config](rest-api-app-config.md) for `GET /config?platform=roku`)
- `POST /auth/login`, `/auth/register`, `/auth/refresh`, `/auth/logout`
- `POST /payments/stripe/create-checkout-session` — start checkout

Content catalog and fields: [Content API and Fields](rest-api-content.md). Each item includes `access` and may redact `media.url` when locked.

## Related guides

- [REST API Overview](rest-api-overview.md)
- [Subscriptions and Apps API](rest-api-subscriptions.md)
- [Content API and Fields](rest-api-content.md)
- [Subscriptions General](subscriptions-general.md)
- [Stripe Checkout Setup](stripe-checkout-setup.md) (checkout REST routes)

## Subscriptions General Settings

URL: https://www.mediablaster.io/docs/subscriptions-general
Category: Subscriptions
Summary: Default access levels, trials, front-end mode, and REST API toggle.

# Subscriptions General Settings

**Location:** MediaBlaster → Subscriptions → **General** tab

Configure site-wide defaults for new content, trials, how subscribers interact with your site, and whether subscription rules affect IPTV feeds.

## Content defaults

| Setting | Description |
|---------|-------------|
| **Default access level for new videos** | Pre-selects free, subscriber, tier, or access-group gating on new posts. Override per video in the [Subscription Access metabox](metabox-subscription-access.md). |
| **Allow free trials** | Enables trial periods defined on tiers. |
| **Default trial length (days)** | Fallback trial duration when a tier does not specify its own. |
| **Hide premium content from public feeds by default** | New premium items stay out of public JSON feeds unless overridden. |
| **Unauthorized behavior default** | Show locked message vs hide content completely when a viewer lacks access. |

## Front-end delivery

| Setting | Description |
|---------|-------------|
| **Front-end mode** | **WordPress** (theme/shortcodes), **Headless** (API-first apps), or **Hybrid** (both). |
| **Enable REST/API access** | Required for mobile apps, headless front ends, and Stripe checkout REST endpoints. |
| **Subscribe page slug** | WordPress page slug used for subscribe redirects (e.g. `subscribe`). |

## Legacy IPTV feeds

| Setting | Description |
|---------|-------------|
| **Apply subscription rules to legacy IPTV feeds** | When off (default), `/wp-json/tv/roku/` includes all published items. When on, premium content may be filtered per entitlement rules — test carefully before enabling in production. |

## Related guides

- [Subscriptions Overview](subscriptions-overview.md)
- [API/Auth settings](subscriptions-api-auth.md)
- [Subscription Access metabox](metabox-subscription-access.md)

## Subscriptions Overview

URL: https://www.mediablaster.io/docs/subscriptions-overview
Category: Subscriptions
Summary: Health snapshot, counts, and configuration warnings for subscriptions.

# Subscriptions Overview

**Location:** MediaBlaster → **Subscriptions** → Overview tab

The subscription system lets you gate premium video, sell plans via Stripe, and expose a REST API for apps. It is **disabled by default**.

## Enable subscriptions

Add this to `wp-config.php` (above the “stop editing” line):

```php
define( 'WPST_SUBSCRIPTIONS_ENABLED', true );
```

A commented example is included in the default Local WP `wp-config.php`. After enabling and reloading wp-admin:

- **MediaBlaster → Subscriptions** — all tabs become available
- **MediaBlaster → Docs** — subscription guides appear in the index (guides marked `requires_subscriptions: true`)

Until `WPST_SUBSCRIPTIONS_ENABLED` is true, subscription menus, Docs subscription section, shortcodes, REST routes, and the Subscription Access metabox are inactive.

There is no working admin toggle for subscriptions on General Settings while the module is disabled; the only master switch is `wp-config.php`. When the module is enabled, General Settings may show a disabled **Coming Soon** switch for documentation only — it does not turn subscriptions on or off.

## Admin tabs

| Tab | Purpose |
|-----|---------|
| **Overview** | Counts, REST status, Stripe diagnostics, configuration warnings |
| **General** | Defaults for access, trials, front-end mode, legacy feed opt-in |
| **API/Auth** | Bearer tokens, login endpoints, HTTPS requirements |
| **Payment Providers** | Stripe checkout, webhooks, keys (PayPal/Apple/Google/Amazon stubs) |
| **Tiers** | Subscription plans, pricing, Stripe Price IDs |
| **Access Groups** | Content bundles assigned to tiers |
| **Subscribers** | User search, manual assign/cancel, Sync from Stripe |
| **Sub Logs** | Payment webhook audit trail |

Each tab shows a short intro paragraph. Hover field labels or the `?` icon for detailed tooltips.

## How access works

MediaBlaster's internal subscription records are the **source of truth** for who can watch premium content. Stripe (and future providers) sync into those records via webhooks — Stripe is a payment provider, not the entitlement engine.

```
Tier → Stripe Price → Checkout → Webhook → Internal subscription → Content access
```

## Quick start path

1. [Subscriptions General](subscriptions-general.md) — set defaults and enable REST if needed.
2. [Payment Providers](subscriptions-payment-providers.md) — enable Stripe.
3. [Stripe Checkout Setup](stripe-checkout-setup.md) — keys, webhooks, pages.
4. [Tiers](subscriptions-tiers.md) — create plans and map Stripe Price IDs.
5. [Access Groups](subscriptions-access-groups.md) — bundle content (optional).
6. Publish pages with [Shortcodes](shortcodes.md) — `[wpst_subscribe]` and `[wpst_account]`.

## Legacy IPTV feeds

The Roku feed at `/wp-json/tv/roku/` is **unchanged** unless you enable **Apply subscription rules to legacy IPTV feeds** on the General tab.

## Vimeo Mass Import

URL: https://www.mediablaster.io/docs/vimeo-mass-import
Category: Vimeo Mass Import
Summary: Guided card-based Vimeo Mass Import with summary stats, Review & Import, and cached library sync.

# Vimeo Mass Import

**Location:** MediaBlaster → **Vimeo Mass Import** (admin slug `r_vimeo_import`)

Choose videos from your connected Vimeo library and import them into MediaBlaster. The page is a **guided import workflow** (not a spreadsheet-style dashboard): a plain-language summary, a video card grid, collapsed import settings, and a **Review & Import** step before bulk imports run.

The default **Show** filter is **Ready to Import** (not imported yet and playable on Vimeo). Imported posts default to **Draft** unless you change post status in Import Settings.

## Prerequisites

1. **Enable Vimeo Integration** on General Settings (saved on).
2. Vimeo connected under [Integrations](integrations-vimeo-oauth.md).
3. At least one post type enabled (Movies, Short Videos, Episodes).
4. Optional import preferences under [Vimeo Settings](vimeo-settings.md) for refreshing existing posts.

## Using the importer

1. Open **MediaBlaster → Vimeo Mass Import**.
2. Confirm the header shows **Connected to Vimeo**.
3. Read the summary (how many videos are ready to import, already imported, or unavailable).
4. Use **Search**, **Show**, and **Sort** to find videos. The default filter is **Ready to Import**.
5. Click **Refresh from Vimeo** in the header to sync your library in batches (recommended for large libraries).
6. Review **Import Settings** on the card above the grid; click **Change settings** to adjust post type, status, thumbnails, tags, and genres.
7. Select videos with **Select** (or the checkbox), then click **Review & Import** in the bottom bar.
8. Confirm details in the review step, then click **Import N Videos** to start the import.
9. For a single video, you can still use **Import** on the card without the review step.

## Page layout

| Area | Purpose |
|------|---------|
| **Header** | Title, intro, **Connected to Vimeo** pill, **Refresh from Vimeo** |
| **Summary** | One sentence: ready to import / already imported / unavailable counts |
| **Toolbar** | Search, **Show** filter, **Sort** only (no refresh in toolbar) |
| **Import Settings** | Collapsed summary card; **Change settings** opens a dialog |
| **Video grid** | Cards with **Select**, status badges, per-card **Import** or **Retry** |
| **Bottom bar** | Appears when videos are selected: **Review & Import**, **Clear Selection** |
| **Loading Data** | Modal with spinner while the library loads (page load, search, filter, pagination) |

Bulk imports always go through **Review & Import** → confirm → **Import N Videos**. Progress shows `Importing X of Y…` and a completion notice.

## Import settings

| Option | Description |
|--------|-------------|
| **Import As** | Target MediaBlaster post type (Movies, Short Videos, Episodes, etc.) |
| **Post Status** | Defaults to **Draft**; choose **Published** only when ready |
| **Import thumbnail** | Sets the WordPress featured image from Vimeo |
| **Import description** | Copies Vimeo description into post content |
| **Import duration** | Saves duration to `rovidx_smarttv_Duration` |
| **Import tags from Vimeo** | Merges Vimeo tags with any selected WordPress tags |
| **Update existing imported videos** | Re-syncs posts that already match the Vimeo URL (allows selecting already-imported videos) |
| **WordPress tags / Genres** | Optional; set in Import Settings (not on the main browse screen) |

## Show filters

| Label | Meaning |
|-------|---------|
| **Ready to Import** | Not in MediaBlaster yet and playable on Vimeo (default) |
| **Already Imported** | A WordPress post already exists for this Vimeo URL |
| **Unavailable** | Vimeo reports the video as private or not playable |
| **Failed Imports** | Import failed during this browser session (use **Retry**) |
| **All Videos** | Full cached library |

## Status labels on cards

| Label | Meaning |
|-------|---------|
| **Already imported** | A WordPress post already exists for this Vimeo URL |
| **Not in MediaBlaster yet** | No matching post yet |
| **Importing…** | Import in progress |
| **Failed** | Import failed during this session (use **Retry**) |
| **Unavailable or private** | Cannot import from Vimeo in current state |

## Troubleshooting

| Symptom | Solution |
|---------|----------|
| **Loading Data** modal stays open | Wait for the AJAX request to finish; check browser Network tab for `mediablaster_vimeo_get_videos` errors |
| **Not connected** | Complete OAuth under **MediaBlaster → Integrations** |
| **All caught up** (empty Ready to Import) | Every playable video is already imported; try **All Videos** or **Refresh from Vimeo** |
| No videos match search | Use **Clear search** in the empty state |
| Empty library after load | Click **Refresh from Vimeo** and wait for sync progress to finish |
| SSL certificate problem | Common on Local WP — MediaBlaster uses the WordPress CA bundle; verify PHP cURL configuration |
| Duplicate imported anyway | Enable **Update existing imported videos** to refresh instead of creating duplicates; duplicates match on `rovidx_smart_tv_vm_pro_url` |

## After import

- Review posts in Movies, Short Videos, or Episodes admin lists (check **Drafts** if you kept the default status).
- Spot-check **Video Data** and featured images.
- Validate entries via `GET /wp-json/mediablaster/v3/content` or [Import and Export](import-export.md).

## Related guides

- [Vimeo OAuth](integrations-vimeo-oauth.md)
- [Vimeo Settings](vimeo-settings.md)
- [Vimeo metabox](metabox-vimeo-import.md)

<!-- Generated from 35 documentation files. -->