WakaVimeo

WakaVimeo integrates with WakaPAC as a plugin, bridging the Vimeo Player SDK into the WakaPAC message model. Playback events, state changes, and volume updates all arrive in msgProc as messages — the same dispatch table as clicks, keypresses, and timers.

Getting Started

Register WakaVimeo with WakaPAC once, before creating any components. The plugin activates automatically for components whose root element is either a <waka-vimeo> custom element, or a <div> carrying a data-vimeo-id attribute. The Vimeo Player SDK script is injected automatically on first use — you do not need to add it yourself.

<script src="https://cdn.jsdelivr.net/gh/quellabs/wakapac@main/wakapac.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/quellabs/wakapac@main/plugins/wakavimeo.min.js"></script>

<script>
    wakaPAC.use(WakaVimeo);
</script>

Custom element

Use <waka-vimeo> as the container element. The plugin detects the tag name and activates automatically. Supply data-vimeo-id to identify the video:

<waka-vimeo data-pac-id="player" data-vimeo-id="76979871"></waka-vimeo>

Attribute-based (classic)

Mark a <div> with a data-vimeo-id attribute holding the numeric Vimeo video ID. The Vimeo Player SDK populates the container with its player DOM (including the iframe) once initialized. The container element itself is not replaced. All embeds use dnt=true (do not track) by default to minimise third-party cookie exposure.

<div data-pac-id="player" data-vimeo-id="76979871"></div>

The Basics

Once registered, Vimeo playback events arrive in msgProc. Control playback through the WakaVimeo API.

wakaPAC('#player', {
    msgProc(event) {
        switch (event.message) {
            case WakaVimeo.MSG_VIDEO_LOADED:
                console.log('Duration:', event.detail.duration);
                console.log('Size:', event.detail.videoWidth, 'x', event.detail.videoHeight);
                // Safe to call play() from here
                WakaVimeo.play(this.pacId);
                break;

            case WakaVimeo.MSG_VIDEO_PLAY:
                this.playing = true;
                break;

            case WakaVimeo.MSG_VIDEO_PAUSE:
                this.playing = false;
                break;

            case WakaVimeo.MSG_VIDEO_ENDED:
                this.playing = false;
                break;

            case WakaVimeo.MSG_VIDEO_ERROR:
                console.error('Playback error:', event.detail.message);
                break;
        }
    }
});

Plugin Options

Pass options to wakaPAC.use() to set page-wide defaults for all Vimeo players:

wakaPAC.use(WakaVimeo, {
    controls:    false,  // Show the native Vimeo control bar (default: false)
    speed:       false,  // Show speed controls; required for setPlaybackRate (default: false)
    transparent: true    // Transparent player background (default: true)
});

Override defaults for a specific player by passing a vimeo config object as the third argument to wakaPAC(). Any valid Vimeo embed option can be passed this way:

wakaPAC('#player', { msgProc(event) { /* ... */ } }, {
    vimeo: { controls: false, loop: true }
});

Messages

The plugin delivers message types to msgProc as playback events occur. All message constants are available on the WakaVimeo object after wakaPAC.use(WakaVimeo) has been called.

Playback Started (MSG_VIDEO_PLAY)

Fired when playback begins, including after a pause or seek.

Playback Paused (MSG_VIDEO_PAUSE)

Fired when playback is paused.

Playback Ended (MSG_VIDEO_ENDED)

Fired when playback reaches the end of the video.

Seek Completed (MSG_VIDEO_SEEK)

Fired after a seek completes. Unlike WakaYouTube, this fires when the player has actually landed on the new position — detail.currentTime reflects the real landed time, which may differ slightly from the requested time depending on the video's keyframe layout.

Metadata Loaded (MSG_VIDEO_LOADED)

Fired when the video's metadata is available — duration and dimensions. This is the earliest point at which duration is valid and WakaVimeo.play() can be called reliably. Also fires when loadVideo() loads a new video into an existing player.

Volume Changed (MSG_VIDEO_VOLUME_CHANGE)

Fired when volume or muted state changes. Unlike WakaYouTube, this fires for both programmatic changes and UI-driven changes made through the Vimeo player controls.

Playback Rate Changed (MSG_VIDEO_RATE_CHANGE)

Fired when the playback rate changes via WakaVimeo.setPlaybackRate() or the player UI. Requires the speed: true embed option and a Vimeo PRO or Business account.

Playback Stalled (MSG_VIDEO_WAITING)

Fired when the player starts buffering. Playback resumes automatically once enough data is available, at which point MSG_VIDEO_CANPLAY fires.

Playback Ready (MSG_VIDEO_CANPLAY)

Fired when buffering ends and playback can resume. Use both messages to drive a buffering indicator:

case WakaVimeo.MSG_VIDEO_WAITING:
    this.buffering = true;
    break;

case WakaVimeo.MSG_VIDEO_CANPLAY:
    this.buffering = false;
    break;

Time Update (MSG_VIDEO_TIMEUPDATE)

Fired at ~250 ms intervals during playback via the Vimeo SDK's timeupdate event. Use this message to drive a progress bar or time display in a companion controls component. Note that unlike WakaVideo and WakaYouTube, Vimeo does not use requestAnimationFrame — updates are less frequent but still sufficient for smooth progress bar rendering.

case WakaVimeo.MSG_VIDEO_TIMEUPDATE:
    this.progressMs = event.wParam;              // integer milliseconds, cheap to read
    this.currentTime = event.detail.currentTime; // fractional seconds, full precision
    break;

Playback Error (MSG_VIDEO_ERROR)

Fired when the Vimeo player reports an error, or when the SDK script fails to load. Unlike WakaYouTube, Vimeo does not use numeric error codes — the error description is always in detail.message.

case WakaVimeo.MSG_VIDEO_ERROR:
    this.error = event.detail.message;
    break;

Reactive Properties

WakaVimeo injects properties onto the component abstraction that are set when metadata loads and remain stable thereafter. Because the video component has no template of its own, these are most useful when read from a companion controls component in response to MSG_VIDEO_LOADED.

API

All API methods take pacId as their first argument. Methods that target a pacId not registered as a Vimeo component are silently ignored.

WakaVimeo.play(pacId)

Starts playback. Call this after MSG_VIDEO_LOADED has fired. Errors such as PasswordError and PrivacyError are dispatched as MSG_VIDEO_ERROR, so all error handling stays in msgProc.

WakaVimeo.pause(pacId)

Pauses playback.

WakaVimeo.seek(pacId, time)

Seeks to a position in seconds. MSG_VIDEO_SEEK fires when the seek completes, carrying the actual landed position which may differ slightly from the requested time.

WakaVimeo.setVolume(pacId, volume)

Sets the volume level. MSG_VIDEO_VOLUME_CHANGE fires from the SDK's volumechange event after the change.

WakaVimeo.setMuted(pacId, muted)

Sets the muted state. MSG_VIDEO_VOLUME_CHANGE fires from the SDK's volumechange event after the change.

WakaVimeo.setPlaybackRate(pacId, rate)

Sets the playback rate. MSG_VIDEO_RATE_CHANGE fires after the change. Requires the speed: true embed option and a Vimeo PRO or Business account.

Best Practices

• Register once: Call wakaPAC.use(WakaVimeo) once before creating any components.
• Wait for MSG_VIDEO_LOADED: Do not call play() or read duration, videoWidth, or videoHeight before this message fires — they are NaN or null until metadata is available.
• Drive progress bars with MSG_VIDEO_TIMEUPDATE: Use event.wParam (milliseconds) for cheap integer comparisons or event.detail.currentTime for full precision. Unlike WakaVideo and WakaYouTube, Vimeo fires at ~250 ms intervals rather than via requestAnimationFrame — smooth for progress bars, but not 60 Hz.
• Use MSG_VIDEO_WAITING / MSG_VIDEO_CANPLAY for buffering indicators: These fire reliably on network conditions. Do not rely on the absence of MSG_VIDEO_TIMEUPDATE as a buffering signal.
• Speed controls require a PRO account: setPlaybackRate() and MSG_VIDEO_RATE_CHANGE require both speed: true in embed options and a Vimeo PRO or Business account. Calls on standard accounts will fail silently.
• Private videos require a URL: If the video privacy setting is "Private", the video ID alone is not sufficient. You must provide the full player URL including the h parameter via the embed options.
• No manual cleanup needed: The plugin destroys the Vimeo.Player instance automatically when the component is destroyed.