|
|
||
|---|---|---|
| .. | ||
| companion | ||
| src | ||
| test | ||
| .gitignore | ||
| .prettierignore | ||
| LICENSE | ||
| README.md | ||
| UPSTREAM.md | ||
| package-lock.json | ||
| package.json | ||
| setup.py | ||
README.md
MPC-HC Companion module — local development
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 for provenance and LICENSE for attribution.
Install on this computer
From the repository root:
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:
- Open the Companion launcher settings (cog).
- Enable Developer Modules and select the parent folder:
/home/beffroi/Documents/Git/beffroi-tools/companion-modules. - In Connections, add MPC-HC: Media Player Classic, selecting version dev.
Use a distinct label such as
MPC_DEVwhile testing. - Set host 192.168.10.146 and port 13579 for the current player.
- 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.
- 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 | Play command; green while playing, amber while paused |
| ■ Stop | Stop command; red while the player reports stopped |
| ◀◀ Previous / ▶▶ Next | Previous/next playlist item, not chapter or seek |
| Mute | Toggle mute; red MUTED when the player mute switch is on |
| 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.
The progress bar fills from left to right. It turns amber with 10 seconds left and red with 5 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.
Loading the next item without playback
The current MPC-HC web API cannot reliably cue the next playlist item in the player without starting it. Both Next File and the playlist-index command open the selected item through MPC-HC's normal autoplay path; neither exposes an open-paused option. Sending Next followed by Stop can briefly play audio/video, so this module does not offer that sequence as a safe cue preset.
To load the next file in MPC-HC itself and keep it at the beginning until Play, MPC-HC needs an open-paused playlist-selection API, or an additional helper on the Windows player computer. Selecting a future item only inside Companion would not preload it in MPC-HC and is not implemented here.
Variables and custom feedback
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 |
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:
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.2.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/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, 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.