# Blue Billywig for WordPress — Editor guide

This is the day-to-day guide for anyone writing posts with videos. The admin-only setup steps live in [admin-guide.md](./admin-guide.md).

## Find your videos

Open **Blue Billywig → Library** in the WP admin sidebar. You see a grid of every clip in your publication, with thumbnails, titles, status badges, and tags.

- **Search** — the box at the top. Matches against title, description, and tags.
- **Folders** — click any folder in the sidebar to scope the grid to its contents. Folders mirror the structure in your OVP admin.
- **Tag chips** — click a tag to add it as a filter; click the × on a chip to remove it.
- **Playlists tab** — the same grid, but showing clip lists instead of individual clips.

Hover a tile to see a silent "moving thumbnail" preview. Click the tile to insert the video into the currently open post.

## Edit a clip without leaving the library

Click **Edit** on any tile. A slide-in drawer opens on the right with a live video preview and a form for every metadata field. The drawer is designed so you can fix a typo and close it without losing your place in the post.

Fields you can change:

- **Title, description, tags** — the usual.
- **Status** — published, draft, or archived.
- **Content protection policy (CPP)** — restricts playback to authenticated users.
- **Playout** — which player skin is used when this clip is embedded with its default playout.
- **Language, publication date** — under the **Advanced** accordion.

The drawer has a "Close automatically after saving" checkbox; toggle it off if you want to make several edits in a row.

### Delete from the drawer

The red **Delete clip** button in the drawer removes the clip from BB. There is no undo.

### Subtitles (captions)

Scroll to the **Subtitles** section. Existing subtitles are listed with their language code and a star that marks the default. Click **+ Upload new subtitle** to add one:

- File: `.vtt` or `.srt`, up to 1 MB.
- Language: pick from the dropdown (populated from your publication).
- Name: optional display label; leave blank for "English captions" style autogeneration.
- Set as default: makes this the one the player shows by default.
- Publish immediately: uncheck if you want to upload a draft and publish it in OVP later.

Click the × next to any subtitle to remove it.

## Call to action on a clip

Scroll to the **Call to action** section. Pick one of three modes:

- **Off** — no CTA.
- **Simple** — fill in a form.
- **Canvas** — drag the CTA on a 16:9 preview to position it.

You can switch between Simple and Canvas at any time without losing your work.

### Click-through CTA

The default type. The CTA is a button that, when clicked, opens a URL.

- **Button label** — what the visitor sees.
- **Target URL** — where they go.
- **Open in new tab** — recommended for external links.
- **Pause video while visible** — halts playback so the viewer's attention is on the CTA.
- **Timing** — when the CTA appears (start) and disappears (end). End = 0 means "until the clip finishes."

### Email-capture CTA (soft gate)

Switch the **Type** radio to **Email capture**. The button becomes an inline email form.

- **Email field placeholder**, **Submit button label**, **Thank-you message** — customize the copy.
- **Submit endpoint** — optional. If your site admin has set up a URL that accepts form submissions (webhook, Zapier, serverless function), paste it here. Leave empty to store submissions only in the visitor's browser.

Submissions are recorded in the visitor's `localStorage` under a `bbtl_{clipId}` key. Once a visitor submits, they're not prompted again on repeat visits.

**This is a soft gate, not a DRM gate.** A visitor who clears their browser storage or opens a private window can dismiss the form again. For hard access control, configure a Content Protection Policy on the clip in OVP — that enforces real authorization.

### Styling

Both modes share the same styling controls:

- Background color, hover color, text color.
- Font family and size (size is a percentage of the canvas so it scales with the player).
- Corner radius, border thickness, border color, background opacity.
- **Background image** — click **Choose…** to pick from your WordPress Media Library, or paste a direct URL.

Live preview updates on every change; nothing is saved until you click **Save CTA**.

### Position presets

In Simple mode, pick from Bottom Center, Bottom Right, Top Right, or End-Screen Fullbleed. Switching to Canvas mode and dragging the widget flips the preset to **Custom**.

### Canvas keyboard controls

Focus the CTA widget (Tab to it or click once), then use arrow keys to nudge position by 1%; add Shift for 5% steps. The SE corner handle (the small square at the bottom-right) is draggable to resize.

## Bulk actions in the library

Hover any tile; a checkbox appears in the corner. Tick checkboxes on multiple tiles to reveal the bulk action bar at the bottom of the screen.

- **Change status** — set the selected clips to Published / Draft / Archived.
- **Move to folder** — pick a folder from your publication; empty = move to root.
- **Set CPP** — apply a content-protection policy; empty = remove protection.
- **Delete selected** — removes clips from BB. Irreversible.

Limits: 50 clips per batch. The bar prevents you from selecting more. For larger batches, process in waves.

## Embed in a post

### Gutenberg

Insert the **Blue Billywig Video** block. The block opens a mini-library grid right inside the editor — search, scope to a folder, click a thumbnail to pick. You can change the pick at any time via the "Change video" button in the sidebar.

Block settings in the sidebar:

- **Playout** — override the publication default for this embed.
- **Autoplay**, **muted**, **loop** — when supported by the playout.
- **Aspect ratio** — defaults to 16:9; set to `auto` for vertical clips.

For playlists, insert the **Blue Billywig Playlist** block instead.

### oEmbed (classic editor or quick paste)

Paste a BB URL on its own line and it auto-embeds. Supported patterns:

- `https://<pub>.bbvms.com/p/<playout>/c/<clipId>.html`
- `https://<pub>.bbvms.com/view/<playout>/<clipId>.html`
- `https://<pub>.bbvms.com/ch/<channelId>.html` (channel embed)

### Shortcode (plugins, custom templates)

```
[blue_billywig id="12345" playout="default"]
```

## Upload a new video

Open **Blue Billywig → Upload**. Drag a file into the drop zone, or click to pick. The file uploads **directly to S3** from your browser — it does not go through your WordPress server, so large files do not hit PHP memory or timeout limits, and upload survives network interruptions (Uppy resumes from the last successful chunk).

Once the upload completes and SAPI has ingested the file, the clip appears in the library at status **uploaded**. Transcoding happens in the background in OVP; the clip becomes **published** once encoding finishes.

## Media Library tab

Under **Media → Add Media**, a new **Blue Billywig** tab shows BB clips alongside your regular WordPress uploads. Use this when you're composing a post and want one embed flow that covers both sources. Inline-edit is available here too — click a clip and the drawer opens.

## Accessibility

- The library drawer is a dialog with focus trap and Esc-to-close.
- The CTA canvas widget is keyboard-operable (arrow keys + Shift arrow).
- Every interactive control has an accessible name.
- The plugin honors the visitor's `prefers-reduced-motion` setting — the drawer slide and the hover-preview fade are disabled.

## Tips and gotchas

- **CTA isn't showing on the live page?** The clip's duration wasn't read yet when you clicked save. Open the drawer, wait for the preview video to buffer, then save again.
- **Subtitle looks garbled?** Most common cause is encoding: save as UTF-8 in your editor.
- **Editing a clip that already has an interactive timeline from elsewhere** (chapters, quizzes, branching) — the plugin refuses to overwrite it. Resolve the CTA in the source tool first, or remove the timeline there.
- **Switching the block from one clip to another** preserves your playout + aspect-ratio settings.

## Keyboard shortcuts

Inside the drawer:

- **Esc** — close. Prompts for confirmation if you have unsaved changes.
- **Tab / Shift-Tab** — move focus between fields without leaving the drawer.

On the CTA canvas:

- **Arrow keys** — nudge CTA position by 1%.
- **Shift + Arrow** — nudge by 5%.

## Getting help

If something is off, note the clip ID (visible in the tile's URL and in the drawer header). Ask your site admin to check `error_log` for lines starting with `Blue Billywig` around the time of the issue — every save/delete is logged with clip and timeline IDs.