# wp-asciiplayer

An Asciicast Player block for WordPress, with real playback in the editor and
backwards-compatible `[asciiplayer]` shortcodes. [中文说明](README-zh.md)

## Install

Install the built `wp-asciiplayer.zip` through **Plugins → Add New → Upload
Plugin**, then activate **Asciicast Player**. A GitHub source ZIP must be built
first; it does not contain generated assets. See [SOURCE.md](SOURCE.md).

Requires WordPress 6.3+ and PHP 7.4+. Compatibility must be checked against your
site and theme; CI tests the versions listed in `.github/workflows/ci.yml`.

## Block editor

1. Insert **Asciicast Player**.
2. Paste an HTTP(S) recording-file URL (for example a `.cast` file), then apply it.
3. Play, pause and seek in the editor. Change theme, speed, looping, controls,
   width/fit, start time and idle-time limit from the block settings.
4. Save the post or page; the same locally bundled player is used on the front end.

Existing saved blocks show a **Load preview** action on reopening the editor.
This keeps external recordings from loading until you choose to preview them.
Preview does not autoplay even when front-end autoplay is enabled.

The source must be a recording-file URL, not an asciinema share-page URL.
A recording on another origin must allow CORS requests from your WordPress site.
HTTP recordings on an HTTPS site may be blocked as mixed content. Use a same-site
HTTPS URL when possible. The plugin does not proxy or copy remote files, grant
new upload types, or add a recording-management post type.

## Existing shortcodes

Old articles remain supported; no content migration is required:

    [asciiplayer]https://example.org/demo.cast[/asciiplayer]
    [asciiplayer theme="monokai" speed="1.5" controls="false"]https://example.org/demo.cast[/asciiplayer]
    [asciiplayer startAt="2" idleTimeLimit="3" style="width: 80%;"]https://example.org/demo.cast[/asciiplayer]

Boolean and numeric options are typed, and historical camelCase options are
normalized after WordPress lowercases shortcode attribute names. Inline styles
are filtered through WordPress safe-CSS handling; unsafe protocols and markup
are rejected/escaped. Unsupported executable/object options are not accepted.
The Classic Editor continues to support shortcodes; it has no custom visual UI.
The block supports a shortcode-to-block transform for supported options. Review
converted settings before saving; articles are never rewritten automatically.

## Local resources and privacy

All player JavaScript, CSS, and WebAssembly are included in the plugin. The old
`ap_use_local_resources` switch is no longer used, and jsDelivr is not contacted.
No analytics or background remote API calls are added.

A recording URL you choose is fetched directly by the visitor's browser. Its host
can receive the visitor's IP address, browser request metadata and possibly a
referrer, according to browser/site policy. Editor previews have the same effect
when you apply a URL or click **Load preview**. Choose a trusted host and review
recordings for sensitive terminal output before publishing them. The host's own
privacy policy applies; the plugin cannot make an external recording private.

## Development

See [SOURCE.md](SOURCE.md) for locked build and ZIP packaging commands. Source
code is GPL-3.0-only. The player and its dependencies retain their own compatible
licenses; see [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).