mirror of
https://github.com/LamGC/wp-asciiplayer.git
synced 2026-10-12 23:33:55 +00:00
Refresh player with native block editor preview and local assets
Preserve shortcode rendering, normalize options, bundle the player locally, and add reproducible packaging and WordPress integration tests.
This commit is contained in:
@@ -1,37 +1,66 @@
|
||||
# wp-asciiplayer
|
||||
|
||||
Play Ascicast files in the post!
|
||||
An Asciicast Player block for WordPress, with real playback in the editor and
|
||||
backwards-compatible `[asciiplayer]` shortcodes. [中文说明](README-zh.md)
|
||||
|
||||
[中文文档](README-zh.md)
|
||||
## Install
|
||||
|
||||
## Quick start
|
||||
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).
|
||||
|
||||
Add a shortcode to the post and enter the following:
|
||||
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`.
|
||||
|
||||
```
|
||||
[asciiplayer]https://asciinema.org/a/28307.cast[/asciiplayer]
|
||||
```
|
||||
## Block editor
|
||||
|
||||
The content of the shortcode is the URL of the ascicast file.
|
||||
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.
|
||||
|
||||
### Options
|
||||
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 AsciiPlayer shortcode supports the options supported by Asciinema-player, such as setting `fit` to `height` and closing the control bar:
|
||||
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.
|
||||
|
||||
```
|
||||
[asciiplayer fit="height" controls="false"]https://asciinema.org/a/28307.cast[/asciiplayer]
|
||||
```
|
||||
## Existing shortcodes
|
||||
|
||||
You can find all available options [here](https://www.npmjs.com/package/asciinema-player#options).
|
||||
Old articles remain supported; no content migration is required:
|
||||
|
||||
> Currently, only the `logger` option is not supported because it requires an object to be passed in.
|
||||
[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]
|
||||
|
||||
#### Style options
|
||||
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.
|
||||
|
||||
For the convenience of customizing player elements,
|
||||
the plugin has added an additional `style` **option**,
|
||||
which corresponds to the `style` **attribute** of the player container element:
|
||||
## Local resources and privacy
|
||||
|
||||
```
|
||||
[asciiplayer style="width: 80%;"]https://asciinema.org/a/28307.cast[/asciiplayer]
|
||||
```
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user