beffroi-tools/companion-modules/media-player-classic
Dandaedre 5b501af6f7
Beffroi/beffroi-tools/pipeline/head This commit looks good Details
Link published mdBook manuals from project READMEs
2026-11-14 22:23:34 +01:00
..
companion Add generated app icons and cross-platform desktop launchers 2026-11-14 14:14:59 +01:00
src Raise Load navigation symbols and enlarge labels 2026-11-12 19:36:23 +01:00
test Raise Load navigation symbols and enlarge labels 2026-11-12 19:36:23 +01:00
.gitignore Add local MPC-HC Companion development module 2026-11-12 07:38:52 +01:00
.prettierignore Add local MPC-HC Companion development module 2026-11-12 07:38:52 +01:00
LICENSE Add local MPC-HC Companion development module 2026-11-12 07:38:52 +01:00
README.md Link published mdBook manuals from project READMEs 2026-11-14 22:23:34 +01:00
UPSTREAM.md Add local MPC-HC Companion development module 2026-11-12 07:38:52 +01:00
package-lock.json Add optional MPC backup player and sync status 2026-11-12 08:38:55 +01:00
package.json Add optional MPC backup player and sync status 2026-11-12 08:38:55 +01:00
setup.py Add local MPC-HC Companion development module 2026-11-12 07:38:52 +01:00

README.md

MPC-HC Companion module — local development

Read the full manual →

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 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:

  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:

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