beffroi-tools/companion-modules/media-player-classic/README.md

470 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# MPC-HC Companion module — local development
[Read the full manual →](https://books.dandaedre.com/manuals/media-player-classic/)
<img src="companion/assets/app-icon.png" width="96" alt="Media Player Classic module icon">
A local development port of the original Media Player Classic module for
**Companion 5.1.0**, using Companion module API 2 and Node.js 22. It preserves
all 138 original numeric command IDs, adds live player feedback, and provides
transport and timing presets.
See [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for attribution.
## Install on this computer
From the repository root:
```sh
python3 companion-modules/media-player-classic/setup.py \
--node-bin /home/beffroi/Softs/companion-x64/resources/node-runtimes/node22/bin \
--companion-config /home/beffroi/.config/companion/config.json \
--package
```
The helper installs dependencies from `package-lock.json`, runs tests and
format checks, optionally builds a `.tgz`, and enables the developer folder.
It backs up the launcher configuration before changing it and preserves other
settings. It refuses to replace an existing different developer folder.
It does not restart Companion, alter connections, or send player commands.
Restart Companion after changing its launcher settings.
Alternatively, install **Node.js 22.20+ (22.x) with npm**, run `python3 setup.py`
inside this module, and configure Companion manually:
1. Open the Companion launcher settings (cog).
2. Enable **Developer Modules** and select the **parent** folder:
`/home/beffroi/Documents/Git/beffroi-tools/companion-modules`.
3. In Connections, add **MPC-HC: Media Player Classic**, selecting version **dev**.
Use a distinct label such as `MPC_DEV` while testing.
4. Set host **192.168.10.146** and port **13579** for the current player.
5. In MPC-HC, enable **View → Options → Player → Web Interface → Listen on port**.
Allow remote access from this Companion computer if the player is on another host.
6. Confirm the connection is OK, then use its presets on a spare button page.
The module appears in Connections; a development module need not appear as an
installed store version on the Modules page. Existing connections remain on
their selected version until you explicitly change them.
## Transport presets and feedback
Open **Presets → MPC_DEV → Transport & timing** and drag the buttons onto a
spare page. These presets already include their feedback and variable references:
| Preset | Behavior |
| --------------------- | ------------------------------------------------------------------------ |
| ▶ Play | Subdued blue while stopped; full green while playing, amber while paused |
| ■ Stop | Subdued red while playing; full red while stopped |
| ◀◀ Previous / ▶▶ Next | Previous/next **playlist item**, not chapter or seek |
| Mute | Neutral when unmuted; full red **MUTED** while muted |
| Pause | Pause command; amber while paused |
| Remaining | Live media countdown and progress bar |
| Elapsed | Live elapsed media time and progress bar |
| Playback state | Playing, paused, stopped, idle, or offline with matching colors |
The Previous/Next transport presets use command IDs verified against this
player's `/commands.json`: Previous → `919`, Next → `920`. The old catalog was
outdated: `918` is **After Playback: Turn off the monitor**, not navigation.
Navigation-related labels are corrected; numeric action IDs still send their
same numeric commands. Re-add copied presets to existing buttons to apply
this correction; linked presets follow the module update.
Transport buttons use white labels on filled backgrounds. Play is subdued blue
until playing, when it becomes full green; Stop is subdued red until stopped,
when it becomes full red. Previous/Next stay subdued blue. Mute is neutral when
unmuted and full red with **MUTED** text when muted. Playback state is full green
while playing, full red while stopped, and amber while paused. Timers stay dark
with progress bars; backup sync keeps its original status colors.
Presets keep Companion’s standard top bar with the button location.
Re-add copied presets to apply styling updates; linked presets update automatically.
The progress bar fills from left to right. It turns amber with 30 seconds left
and red with 10 seconds left. Timing displays are passive: pressing them does
not send a player command. Transport presets use symbols, colors, and labels;
all original text presets remain in **All commands**.
Feedback comes from the player, including changes made using the mouse,
keyboard, or another controller. It never assumes a command succeeded merely
because a button was pressed. A successful HTTP command response alone does
not change playback or mute feedback. The next player status determines it.
Status uses `/status.json` where available (verified on MPC-HC **2.8.5.0**),
with automatic `/variables.html` fallback for older builds. The module polls
at **500 ms** by default, configurable from **250–5000 ms**, and refreshes after
commands. Requests do not overlap, and polling resumes after network failures.
On a failed status request, active state feedback and stale timing values are
cleared; transport presets show **OFFLINE**. Requests time out after 2.5 seconds.
There can therefore be a polling interval plus timeout before loss is shown.
`idle` means MPC reports no active media graph; it is distinct from `stopped`.
Unknown duration shows `--:--` with no bar. Countdown reflects media time, pauses
with the player, follows seeks, and does not predict wall-clock completion at
nonstandard playback speeds. Playback state is MPC's reported state, not proof
that frames or audio are physically reaching an output device.
## Large three-button timers
Open **Presets → MPC_DEV → Timers — large HH / MM / SS**. Place **Remaining HH
(1/3)**, **Remaining MM (2/3)**, and **Remaining SS (3/3)** in three adjacent slots,
left to right. For example, one hour, two minutes and three seconds displays:
| HH | MM | SS |
| --- | --- | --- |
| 01 | 02 | 03 |
There is a matching **Elapsed** set. Inspired by Ontime's separate timer-component
presets, each button shows only large auto-sized digits on a dark background,
with Companion's standard location bar. Buttons are passive; pressing them does
not control playback. The hours field does not wrap at 24 hours.
Remaining time rounds up once before splitting; elapsed time rounds down. Both
follow the same player snapshots as the existing timers and freeze when paused.
All remaining digits turn amber at 30 seconds left and red at 10 seconds left.
Elapsed digits stay white. Offline/idle displays grey **-- | -- | --**; unknown
duration also makes the remaining timer unavailable. Elapsed time still works
when position is known but duration is not.
Custom buttons can use `remaining_hh`, `remaining_mm`, `remaining_ss`,
`elapsed_hh`, `elapsed_mm`, and `elapsed_ss`. These are zero-padded display strings;
existing total-second variables are unchanged. Backup equivalents have `backup_`
prefixes. The new presets follow the main player.
## Playlist — direct playback
**Presets → MPC_DEV → Playlist** contains **Play item 1–10**. Each sends MPC-HC's
normal indexed playlist selection command, which opens and plays that item.
These presets do **not** mute, stop, retry Stop, or run the experimental loading
sequence. Existing mute remains unchanged. Even the currently selected item is
sent through MPC-HC's normal open/play path.
The reusable **Play playlist item** action accepts a 1-based item number from
1–10000. Duplicate a preset, change its action number and button text to create
additional positions. The action checks `/playlist.json` before sending selection;
missing items send no playback command. Positions follow the current playlist
order, so keep main/backup playlists aligned. Player target defaults to Both.
The buttons stay muted blue with a play icon; they do not claim individual-item
playing feedback. Normal player feedback updates after selection. These actions
leave **Last load result** unchanged because they are not experimental loads.
Like other transport actions, they are ignored while an experimental load is running.
## EXPERIMENTAL — Load next / previous / playlist item: not a guaranteed cue/preload
> **EXPERIMENTAL: these buttons deliberately start the next or previous video,
> then try to stop it. They do not load an item paused, and cannot guarantee that
> no moving frames reach the output. Load next has been reported working on the
> user's MPC-HC setup. Load previous shares that sequence but still needs its own
> real-player check. Both remain experimental; success on one setup does not
> establish reliable production cue/preload behavior for other media or systems.**
Find **Load previous** and **Load next** under **Presets → MPC_DEV → Experimental**.
The folder identifies their experimental nature; names and button labels omit
EXP. Existing copied buttons need re-adding to remove the old label; linked
presets update. These buttons remain separate from regular transport presets.
**Do not first test this on a live program output.** Use a spare button and an
output where brief playback is acceptable. Observe the actual video and listen
to the actual audio; a green connection indicator or successful HTTP response
is not proof that the output was silent or that no frames played.
**What this experiment does and does not guarantee:**
- It waits for MPC-HC's _reported_ mute state before advancing. This is not a
measurement of physical audio output, and another controller can change mute.
- It intentionally sends the normal autoplaying Next or Previous command. Stop can arrive
before loading finishes or take effect late; retries reduce this risk but do
not remove it. Network delays and player behavior affect the result.
- **LOADED NEXT / LOADED PREV is a status-based confirmation, not a guarantee of seamless
preload.** It means a different reported filename remained stopped for at
least 500 ms and the original mute setting was confirmed. It does not prove
which playlist entry was selected, that no frames played, or where playback
will resume. Check these on your player and media.
- Failure can leave the new file playing but muted if Stop cannot be delivered
or applied. **FAILED NEXT / FAILED PREV does not mean the player is safely stopped.** Inspect
MPC-HC before manually unmuting, playing, or pressing either Load button again.
- A configured backup has its own outcome. Main success does not certify the
backup. A player that was already muted stays muted after success.
### Experimental sequence
1. Read fresh state and remember the current file and mute setting.
2. Mute if needed and wait for player feedback confirming mute. Never retry a
mute toggle blindly; if mute cannot be confirmed, do not advance.
3. Send Next File (`920`) or Previous File (`919`) once, then Stop (`890`) immediately after its HTTP
response, without waiting for a status poll in between.
4. Check about every 50 ms (plus HTTP latency), retrying Stop while not stopped.
Require a different nonempty filename and stopped state continuously observed
for at least 500 ms. Each confirmation phase has a 5-second deadline; an
in-flight request can add its normal 2.5-second timeout.
5. Only then restore the original mute setting and confirm it. A player that
started muted stays muted.
Each navigation button shows **LOADING**, then **LOADED** or **FAILED** with
**NEXT** or **PREV**. Two seconds after completion it returns to **LOAD NEXT** or
**LOAD PREV** (with its arrow icon). This display reset does not send a command
or erase the result. Offline still overrides the navigation buttons.
Add the passive **Last load result** preset from **Experimental** for a retained
record. It shows **NO LOAD YET** initially, amber **LOADING**, blue **LOADED** plus the start of the video name,
or red **LAST FAILED**, with the direction. The latest result stays until the
next load attempt, even after Play, Stop, a file change, or a disconnect. This is
**history, not confirmation that the player is still stopped or connected**.
Connection reconfiguration or module restart resets it. Pressing it does nothing.
`load_result_status`, `load_result_direction`, `load_result_file`, and
`load_result_detail` expose the retained result; add `backup_` for the backup.
The filename is recorded on success; failure details explain the problem.
The result button displays up to 16 visible characters of the basename (extension
omitted), split over two lines and ending with an ellipsis when truncated. The
full filename remains in `load_result_file`; `file` is the current player filename.
The display uses the retained successful-load filename, not a later playing file.
`load_next_status` / `load_next_detail` and `load_previous_status` /
`load_previous_detail` retain their existing operation/current-state behavior.
Starting one direction resets the other direction's result to idle. These
variables are not subject to the two-second button-display reset.
The presets follow the main player. Each targeted player runs independently.
The default target is Both; no backup is required. Main success does not imply
backup success—check backup/sync status and the backup result variables.
Repeated presses while running, including the opposite direction, are coalesced;
they do not queue another navigation. Other module commands are ignored
until the sequence finishes, to prevent Play or Mute from interfering. Direct
MPC-HC control or another connection can still interfere. Reconfiguration and
module shutdown cancel the sequence without attempting to unmute.
If loading cannot be confirmed, the action attempts a final Stop and does not
restore audio. Check the player before manually unmuting or trying again. If a
network error occurs during the final unmute, its outcome is unknown; the action
reports failure and never blindly repeats the toggle.
The web status reports a filename, not a playlist-entry identity. Consecutive
entries with the same reported filename, a single-item loop, or reaching either end
without changing files cannot be confirmed and remain muted. A different filename
following the single navigation command is the available evidence of movement;
external playlist changes cannot be distinguished. True preload without any
playback still requires an MPC-HC open-paused API or a helper on the player PC.
### Load a specific playlist item
**Load playlist item 1–10** presets are in **Experimental**. They use the same
experimental mute → select → Stop → verify → restore-mute sequence and the same
two-second result display. **Last load result** retains the outcome as **#1**, **#2**,
on failures/in-progress; successful results show the video name.
`load_result_direction` contains `item_1`, `item_2`, etc.
Load next / previous use separate symbol and label layers, with the symbol raised
to leave room for larger text. Re-add existing copied presets to get the new layout.
Numbered Load presets use Companion 5 layered graphics: a small **↓ LOAD** title
above a large item number. Re-add existing copied presets to get this layout;
linked presets update automatically.
The action is reusable, not limited to ten items. Duplicate a numbered preset
and edit **Playlist item number (1 = first)** in its action and all three **Load
playlist item state** feedbacks to the same number. Set the large number text
layer to match. The small title and large number are separate editable layers.
Numbers from 1 to 10000 are supported, subject to the actual playlist length.
The title changes for loading, loaded, failed, or offline; the large number stays visible.
These are **playlist positions, not saved file identities**. Reordering a playlist
changes what a numbered button loads. Presets remain available even if the
playlist has fewer than ten entries. Each press fetches `/playlist.json` and
rejects absent items before muting or navigating. An unsupported or malformed
playlist response also aborts without starting the sequence; relative Load
next/previous do not require this endpoint. Names are not embedded in presets,
so a copied button cannot silently retain an old filename label after reordering.
Each player validates its own playlist and selects the same item number. Keep
main and backup playlists in matching order. The action does not map filenames
between players, and main success does not imply backup success.
Indexed loading uses MPC-HC's `wm_command=-3&index=N` with zero-based numbering
internally. It checks the selected index as well as stopped state and a changed
filename, and aborts if the playlist entries/labels/durations change during the
sequence. A selected index can update before the media has loaded, so it is not
sufficient evidence by itself. Different entries with the same reported filename
still cannot be confirmed safely and leave audio muted after timeout.
If the requested item is already selected with media loaded, it is stopped in
place without reopening it; the original mute setting is preserved. If the
player is idle, it opens the selected item instead. **Indexed loading can briefly
play video too. It remains experimental and needs real-player testing.** Failed
validation before muting leaves the original audio setting untouched.
### Before considering this usable for your show
Test stopped and playing starting states; initially muted and unmuted audio;
slow-loading files; the first and last playlist entries; repeat/loop behavior; duplicate
filenames; connection loss; repeated presses; and main/backup failures. Confirm
that Play starts the loaded media from the expected position. Keep using the
regular transport controls until this experiment is satisfactory with your
actual player, media, network, and output routing. This label remains experimental
until explicitly reviewed and promoted; success in mocks alone is insufficient.
## Optional backup player
In this connection's configuration, keep your existing **Main player** host/port
and optionally fill in **Backup IP address or hostname** and its web-interface
port. Leave the backup host blank when using one player. The module does not
infer a backup address from other connections.
All actions now have a **Player target** option: **Both players** (default),
**Main only**, or **Backup only**. Existing buttons without the option also
use Both. With no backup configured, Both sends only to the main. Each player
receives its command independently; failure or delay on one does not prevent
delivery to the other. Commands are not retried.
The main player remains authoritative for normal transport feedback, countdown,
progress, existing variables, and connection health. Backup failures do not
turn this connection red or generate recurring error logs. The module does not
promote the backup to main or switch video outputs automatically.
Add **Backup sync status** from **Transport & timing**. This is a passive display:
pressing it does not start playback or force synchronization.
| Display | Color | Meaning |
| ------------------------- | ----- | ---------------------------------------------------- |
| No backup | Grey | Backup address is blank |
| Backup offline | Blue | Configured backup has no available status |
| Backup empty | Blue | Backup responds but has no active media |
| Backup config | Blue | Invalid backup address/port or same endpoint as main |
| In sync | Green | Both players agree within the configured tolerance |
| Out of sync | Red | Media, state, speed, or timing differs |
| Main offline / Main empty | Amber | Main cannot provide a usable reference |
| Checking sync | Blue | Waiting for fresh samples |
Comparison uses case-insensitive filenames (allowing different media folders),
duration, playback state, playback rate, and estimated position. The default
**Playback sync tolerance** is **1000 ms**, configurable from 100–10000 ms.
Sample timestamps and playback rates compensate for different poll arrival
times; this is a monitoring estimate, not frame-accurate synchronization or a
media-content checksum. A brief mismatch can appear while files load or commands
reach the two players. Use the same ordered playlists on both machines.
**Include mute and volume in sync comparison** is off by default, allowing an
intentionally silent backup. Enable it if audio settings should match too.
Toggle commands (such as Mute) are sent to each player as-is; they do not copy
the main's state to the backup or repair an existing mismatch. Use Main only or
Backup only actions to correct the relevant player independently.
Use distinct player addresses. An identical configured endpoint is rejected as
a backup to prevent double commands; different hostnames resolving to the same
machine are not detected. Unavailable backup states remain informational.
For custom buttons, `sync_label` provides display text, `sync_status` a stable
code (`no_backup`, `backup_offline`, `backup_empty`, `backup_config`, `in_sync`,
`out_of_sync`, `main_offline`, `main_empty`, `checking`), and `sync_detail` explains
the comparison. `backup_offset_ms` is estimated backup minus main position;
positive means ahead. Every main variable also has a `backup_` counterpart,
plus `backup_configured` and `backup_status`. Unknown values are cleared;
Companion can display null values as empty strings. **Backup in sync with main**,
**Backup out of sync with main**, and **Backup sync status** feedbacks are available
for custom buttons.
## Variables and custom feedback
The elapsed preset uses **ELAPSED** with size 14 text to avoid wrapping. The
playback-state preset uses size 14 text to display **Playing**, **Paused**,
**Stopped**, or **Idle** without clipping.
These are connection/module variables, not button-local variables. With the
connection labelled `MPC_DEV`, use `$(MPC_DEV:remaining)` in button text.
Presets are wired automatically to the connection label.
| Variables | Values |
| ---------------------------------------------------------- | ----------------------------------------------------------- |
| `state`, `connected` | Playback state string and status availability boolean |
| `playing`, `stopped`, `paused`, `muted` | Booleans; null when status is unavailable |
| `volume`, `file`, `version`, `rate` | Volume percent, filename, player version, playback rate |
| `elapsed`, `duration`, `remaining` | Formatted time (`MM:SS` or `H:MM:SS`); `--:--` when unknown |
| `elapsed_seconds`, `duration_seconds`, `remaining_seconds` | Numeric media seconds; null when unknown |
| `progress` | Percentage from 0 to 100; null when duration is unknown |
`state_label` provides capitalized display text; `state` retains lowercase values
for expressions and existing buttons.
Mute is separate from volume zero: `muted` follows MPC's mute switch.
For existing/custom buttons, add **Playing**, **Stopped**, **Paused**, **Audio
muted**, **No active media (idle)**, **Status unavailable**, or **Playback progress
bar** from the module's Feedbacks list. Existing buttons are not rewritten;
replace them with transport presets or add feedback manually.
## Edit, test, and update
On this machine, use the bundled runtime in a terminal:
```sh
export PATH="/home/beffroi/Softs/companion-x64/resources/node-runtimes/node22/bin:$PATH"
cd companion-modules/media-player-classic
npm test
npm run check
npm run format # apply formatting after edits
npm run package # produce media-player-classic-1.3.0-dev.0.tgz
```
Companion watches the developer folder and reloads the module after source
changes. No copying or packaging is needed for everyday edits. Disable and
re-enable `MPC_DEV` if a reload does not occur. Changes briefly interrupt only
connections using this development module.
After pulling dependency updates, rerun `setup.py` (without
`--companion-config` if already configured). It uses `npm ci` to reproduce the
locked dependency versions. Keep the lockfile committed. Packages, dependencies,
and npm caches are ignored by Git.
For another computer later, build the package and import the `.tgz` through
Companion's Modules page. Test the packaged build separately from source.
No fork, publishing, or additional update server is required for local use.
## Layout
- `src/main.js`: Companion lifecycle, configuration, and connection status.
- `src/client.js`: HTTP transport, timeout, and cancellation.
- `src/player.js`: independent player polling and command lifecycle.
- `src/redundancy.js`: backup comparison and variables.
- `src/commands.js`: original command catalog and stable action IDs.
- `src/definitions.js`: action and preset definitions.
- `src/state.js`: JSON/HTML normalization, timing, and module variables.
- `src/feedbacks.js`: state feedback and RGBA progress graphics.
- `test/`: mock HTTP integration tests; never contact the real player.
- `companion/HELP.md`: help displayed inside Companion.
## Battle-testing checklist
Automated tests exercise all 138 command URLs against a mock server, HTTP errors,
redirect refusal, timeout, cancellation, JSON/HTML parsing, feedback states,
countdown/progress edge cases, polling recovery, independent dual-player delivery,
main authority, optional backup failures, comparison tolerance, and configuration validation. They do
not establish that every legacy command still works in current MPC-HC.
On a spare page with a disposable media file:
- Record the exact MPC-HC version, Companion version, and module Git commit.
- Check Play, Pause, Stop, seeking, volume, mute, fullscreen, and playlist navigation.
- Check presets render and trigger the expected action once.
- Disable the player web interface, trigger an action, and confirm a useful error.
Re-enable it and confirm the next action succeeds; commands are never retried.
- Edit the module and verify reload; disable/re-enable its connection.
- Restart Companion and verify the developer connection returns.
- Test existing button compatibility before moving your normal MPC connection to dev.
- Import and smoke-test a packaged build before upstreaming.
Live validation reads status and renders presets inside Companion without
sending playback commands. Use the checklist above to test actual playback,
mute/unmute, seeks, end-of-file behavior, and playlist navigation on your media.
Open File opens the player's dialog; it does not accept or upload a path.
To roll back, select the official version for any connection using dev, or remove
`MPC_DEV`, disable Developer Modules, and restart Companion. The helper's
`config.json.before-mpc-dev-*` backup can restore launcher settings while Companion
is stopped. Your normal button configuration is not changed by the helper.
## References
- [Companion developer folders](https://companion.free/for-developers/module-development/local-modules/)
- [Module packaging](https://companion.free/for-developers/module-development/module-lifecycle/module-packaging/)
- [Original MPC module](https://github.com/bitfocus/companion-module-media-player-classic)
- [MPC-HC status endpoints](https://github.com/clsid2/mpc-hc/blob/develop/src/mpc-hc/WebClientSocket.cpp)
- [Ontime progress feedback reference](https://github.com/bitfocus/companion-module-getontime-ontime/blob/main/src/feedbacks/progress.ts)