Vimeo Player API for JavaScript control and events

Attaching Player.js to an embedded Vimeo video

Vimeo Player API solves a focused problem for pages that embed Vimeo video. It gives frontend code a Player object with documented methods and event callbacks for interacting with an embedded player. Its users include site builders and application developers who need custom playback controls, metadata access, or reactions to player events without limiting the page to Vimeo's default embed interface.

The README documents a short path for an existing player. Pass an existing Vimeo iframe element to `Vimeo.Player`, register any required callbacks, and call the available methods. The constructor becomes the application's control point while the iframe continues to supply the video experience.

<iframe src="https://player.vimeo.com/video/76979871?h=8272103f6e" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>

<script src="https://player.vimeo.com/api/player.js"></script>
<script>
    const iframe = document.querySelector('iframe');
    const player = new Vimeo.Player(iframe);

    player.on('play', function() {
        console.log('played the video!');
    });
</script>

The browser build attaches the constructor as `Vimeo.Player`. In this example, the callback runs when Vimeo reports a `play` event. An application could connect that event to its own interface or analytics logic, although the README does not prescribe a particular interface component.

This package does not replace Vimeo's hosted player or provide local video hosting. The repository description identifies its purpose as interacting with and controlling an embedded Vimeo Player. The README also documents embed options, text-track operations, audio-track selection, video loading, and readiness methods. That makes it more capable than a static iframe tag, but its scope remains tied to Vimeo-hosted embeds.

Creating Vimeo embeds from IDs, URLs, or attributes

An application does not have to generate its iframe before using Player.js. The constructor can create an embed inside an empty element by receiving a selector and an options object. The README gives `id`, `width`, and `loop` as concrete options:

<div id="made-in-ny"></div>

<script src="https://player.vimeo.com/api/player.js"></script>
<script>
    const options = {
        id: 59777392,
        width: 640,
        loop: true
    };

    const player = new Vimeo.Player('made-in-ny', options);
    player.setVolume(0);
</script>

The first argument identifies the empty container. The options tell the library which Vimeo video to embed and how the generated iframe should be configured. The README also accepts a Vimeo URL, which is important for unlisted videos. Its privacy note says that an unlisted video requires the full URL in a `url` property, including the `h` parameter, rather than supplying only an `id` property.

A second creation route relies on HTML attributes. When player.js loads, it scans the document for elements with `data-vimeo-id` or `data-vimeo-url`. Other embed settings can use the `data-vimeo` prefix:

<div data-vimeo-id="19231868" data-vimeo-width="640" id="handstick"></div>
<script src="https://player.vimeo.com/api/player.js"></script>

That example supports a page whose markup describes the embed directly. Automatic scanning reduces JavaScript setup for presentation, but it creates initialization through markup discovery. If the application needs to control the player, it must still construct a `Vimeo.Player` object using the container or generated iframe.

The constructor offers explicit control, while data attributes favor declarative page markup. Neither path changes Vimeo's hosting model. Also, embed options apply only when Player.js creates a new embed. They do not reconfigure a pre-existing iframe passed to the constructor.

Installing @vimeo/player for npm or direct browser use

The README gives two installation routes. A JavaScript project using a package manager can install the published `@vimeo/player` package:

npm install @vimeo/player

The repository's `package.json` identifies the current package version as `2.30.4`. It points CommonJS consumers to `dist/player.js`, module-aware bundlers to `dist/player.es.js`, and TypeScript users to `types/player.d.ts`. Its published files include `src`, `dist`, and `types`, so consumers receive runtime builds, source files, and declarations as listed by npm packaging metadata.

For a page without a build step, the browser build can be loaded from Vimeo's CDN:

<script src="https://player.vimeo.com/api/player.js"></script>

The README calls this an up-to-date version, but the example does not provide a version-pinned URL. A team that requires repeatable deployments would need to account for that distinction in its own release policy. The README does not document an integrity value, fallback URL, or Content Security Policy configuration for the CDN script.

Webpack, Rollup, and similar bundlers use the package export instead of the browser global. The documented import gives the constructor directly:

import Player from '@vimeo/player';

const player = new Player('handstick', {
    id: 19231868,
    width: 640
});

RequireJS is also supported, but the README warns against loading the script as an ordinary static file in that environment. It must use RequireJS's dynamic load system:

<script>
    require(['https://player.vimeo.com/api/player.js'], function (Player) {
        const iframe = document.querySelector('iframe');
        const player = new Player(iframe);

        player.on('play', function() {
            console.log('played the video!');
        });
    });
</script>

In each route, the reader should end up with a Player constructor: `Vimeo.Player` from the browser global or the imported `Player` object in a loader environment.

Player.js events, promises, and error surfaces

Player.js combines command methods, metadata queries, and event registration. The documented API includes `on`, `off`, `loadVideo`, `ready`, text-track methods, and `selectAudioTrack`. Some operations return promises, while event handlers receive named player events.

The distinction affects application design. Metadata retrieval is asynchronous, so a caller must wait for the returned promise. Event registration connects application behavior to changes reported by the player. Initialization is separate from control: creating an embed, obtaining a Player object, waiting for readiness, and subscribing to events are distinct steps.

player.getVideoTitle().then(function(title) {
    console.log('title:', title);
});

player.on('play', function() {
    console.log('played the video!');
});

Here, the title request returns a promise, while `on('play', ...)` registers a callback. Rejected operations must be handled according to the method's documented error type. The README's API index names `TypeError`, `PasswordError`, `InvalidTrackLanguageError`, `InvalidTrackError`, `NoAudioTracksError`, `NoAlternateAudioTracksError`, and `NoMatchingAudioTrackError` in method signatures.

Those errors show that video privacy, missing tracks, and unavailable language or audio selections can affect runtime behavior. A password-protected video or a track request that cannot be satisfied is different from a syntax failure in the surrounding page. However, the README excerpt does not reproduce the full description of each failure path. Engineers selecting Player.js should consult the repository's method documentation and type declarations for the precise contract before depending on timing or recovery behavior.

The README also does not document offline playback, media downloading, or a player-independent fallback when Vimeo cannot load. Native-promise and weak-map packages appear in `package.json`, but they are implementation dependencies. They do not turn the hosted Vimeo embed into a local media engine.

Player.js browser scope and integration limits

The README limits browser support to the last two versions of Edge, Firefox, Safari, Opera, and Chrome, including Chromium-based browsers. That policy is narrower than support for every browser version an application might encounter. Projects that must retain an older browser need to verify the API behavior there or maintain a separate experience.

The documented browser support is not the only integration boundary. Player.js depends on a Vimeo player element being present or created, and it needs access to the script when using the browser build. A Content Security Policy can also affect whether and how the page may load external player code, but the README does not provide CSP instructions. The package repository cannot confirm the behavior of a particular site's CSP, network firewall, consent platform, or extension.

Video visibility is another boundary. The README explicitly calls out unlisted videos and the need for the full URL with its `h` parameter. That privacy detail is operationally important because an ID-only construction path may not be sufficient for that class of video. The project does not document a general bypass for privacy restrictions, and its intended mechanisms remain ordinary embed options and Player object methods.

Automatic initialization introduces another constraint. The browser build scans for `data-vimeo-id` and `data-vimeo-url`, but control still requires a Player object. A page can therefore produce an embed without exposing it to application code. Explicit construction is more verbose, yet it gives the developer a clear place to register events and call methods.

These constraints make Player.js suitable for conventional Vimeo embeds in current browsers. They also make it the wrong foundation when the page needs an abstraction over several unrelated video providers. The library's object model and examples are Vimeo-specific.

Player.js releases, licensing, and upgrade work

Repository facts show current release activity. The repository is not archived, the last push was on 2026-06-10, and recent tags include `v2.30.4` on 2026-04-29, `v2.30.3` on 2026-03-04, and `v2.30.2` on 2026-01-30. The package metadata also reports version `2.30.4`. These facts support continued release attention, but they do not guarantee that every application will have a zero-cost upgrade.

Upgrading may require more than changing a dependency range. The package publishes both CommonJS and module builds, and it includes a TypeScript declaration file. A consuming project may need to review its bundler entry points, imported constructor form, event typings, and promise rejection handling. The README does not publish a migration guide or list breaking changes for the cited releases, so the repository history and release contents are the relevant sources for that comparison.

The repository's development scripts also show the project's own workflow. `npm run build` invokes the Rollup build after a clean step, `npm run lint` checks `src/` and `test/`, `npm test` runs AVA with coverage, and `npm run check-types` invokes TypeScript compilation. These scripts concern maintainers working in the repository; they are not required installation commands for an application that consumes the package.

The package is licensed under MIT. The MIT license permits broad use, modification, distribution, and sale, subject to its conditions and disclaimer. That is a license summary rather than legal advice. Distribution notices and any separate Vimeo service terms should be reviewed when they apply, but the README does not provide legal interpretation.

Choosing Player.js instead of a plain Vimeo iframe

The most direct alternative is a plain Vimeo iframe with no Player.js layer. Both approaches can place a hosted Vimeo video on a page. The difference is the interface available after embedding. A plain iframe can display Vimeo's player but does not give the page the documented Player.js methods or event callbacks. Player.js sits beside the embed and exposes those operations to JavaScript.

That difference favors Player.js when an application needs custom controls, title retrieval, readiness handling, track selection, or player events. A plain iframe is simpler when the page only needs to present the video and no application behavior depends on player state. Adding Player.js is unnecessary for that limited case.

The npm package and CDN script are also alternatives in how they reach the browser. npm places the library under application dependency control and supports the documented module import. The CDN exposes a browser global through a script element. The README does not publish comparative bundle sizes or performance measurements, so it offers no basis for claiming one delivery method is faster or smaller.

There is a further choice between explicit and declarative initialization. Explicit construction lets the application define the target and options in JavaScript. Data attributes let the browser build discover videos already declared in HTML. Declarative markup is convenient for simple pages, while explicit construction is easier to inspect when initialization order or several Player instances matter.

For a multi-provider video layer, a provider-neutral abstraction would offer a different approach, but the repository does not document one. Player.js itself targets Vimeo, so migration away from Vimeo or support for unrelated hosts would require another control interface.

Editorial conclusion

Adopt @vimeo/player when an application needs scripted control over an embedded Vimeo video, particularly when an existing iframe or generated embed already supplies the media context. Do not choose it for local video playback, downloading media, or non-Vimeo hosting, because the package specifically interfaces with Vimeo players. Verify first that the page can load the player script, that the target video is accessible under its privacy settings, and that the documented methods cover the required behavior. The repository uses the MIT license, publishes version 2.30.4, and records its last push as 2026-06-10.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vimeo/player.js on GitHub