Kinescope module for Drupal

If your site runs on Drupal, you can add Kinescope videos to your content with the Kinescope module. You paste a video link into a field, and the module renders the Kinescope player on the page. The module supports Drupal 10 and 11. The current version is 1.3.1.

The module is developed and maintained by Kinescope partners. For questions and bugs in the module, use the project issue queue on drupal.org.

When the module helps

• Video in content — a player in an article, on a page, or in a block through a dedicated field.
• Video in the Drupal media library — Kinescope videos sit next to images and documents, and you can reuse them in any content.
• Video details without manual input — with an API token, the module pulls in the title, description, duration, and poster.
• Player control from JavaScript — the module connects the IFrame API, and you handle player events in your theme code.
• Video in a popup — the page shows a poster with a link, and the player opens on top of the page.

If any of these sound familiar, read on.

What the module includes

The project is split into four modules. Enable only the ones you need.

How the module works (4 steps)

1. You upload a video to Kinescope and copy its link.
2. You paste the link into a Kinescope field or add the video to the Drupal media library.
3. If an API token is set, the module requests the video details from Kinescope.
4. Drupal renders the Kinescope player with the selected embed method.

Now let’s set it up.

Installation

1. Install the module with Composer:

   composer require drupal/kinescope
   

2. In the Drupal admin, open Extend (/admin/modules).

3. Check Kinescope and Kinescope Player. If needed, also check Kinescope Media and Kinescope Popup.

4. Click Install.

Module settings

All settings are on the Configuration → Media → Kinescope settings page (/admin/config/media/kinescope). Only roles with the Administer Kinescope settings permission can open it.

Tokenless and token-authorized modes

The module works without an API token — this is the default mode. A token adds video details from the Kinescope API.

With a token, the module requests the video details with GET /v1/videos/{video_id}.

To connect a token:

1. In Kinescope, open Settings → API tokens and create a token. Learn more about tokens in General API rules.
2. In Drupal, paste the token into the API token field on the Kinescope settings page.
3. Click Save configuration.

You can also set the token in settings.php:

// Kinescope API token for the Kinescope module
$settings['kinescope.api_token'] = 'YOUR_API_TOKEN';

The value from settings.php takes priority: the API token field in the form becomes read-only, and a note below it says that the token is set in the file.

To check whether Drupal sees the token, open Reports → Status report (/admin/reports/status). The Kinescope API token row shows Configured or a Not configured warning.

Player embed method

On the same page, in the Player section, choose the Embed method. This setting is global: it applies to every Kinescope field on the site.

IFrame API. The module only connects the player to the IFrame API. You add the code that controls the player and handles its events to your theme yourself — see the examples in IFrame API auto-connect.

Web Components. In this mode, the module passes only the video link to the element. Width, height, and the Allow-list options value from the field settings are not applied.

Video in a content field

This method does not need the media library: the video lives right in the content field. You can add a Kinescope field to any entity type — a node, a block, or a paragraph.

1. Open Structure → Content types and choose a content type.
2. Click Manage fields and add a new field of the Kinescope type.
3. In the field settings, decide who sets the player parameters. The Allow editors to override player settings per video checkbox controls this:
   • checked (default) — editors set the parameters for each video in the content form;
   • unchecked — you set the parameters once in the field settings, and they apply to every video in the field.
4. Save the field settings.

Player parameters:

Now add a video to your content:

1. In Kinescope, copy the video link: the “Link” button above the player → “Copy”.
2. In the content form, paste it into the Kinescope URL field.
3. Save the content. The Kinescope ID field fills in automatically.

The field accepts links like these:

• https://kinescope.io/VIDEO_ID
• https://kinescope.io/embed/VIDEO_ID

The link must start with https:// and have no parameters after ?. Otherwise Drupal shows the The Kinescope URL is not valid error.

Video in the Drupal media library

For this method, enable Kinescope Media. The module does not create a media type on its own — add one once:

1. Open Structure → Media types → Add media type (/admin/structure/media/add).
2. Enter a name, for example “Kinescope”.
3. In Media source, choose Kinescope and save the type.

Drupal creates a Kinescope URL field in the media type. The form has no name field: the module sets the name itself — from the Kinescope API, or as Kinescope: video ID if no token is set.

You can add a video to the media library in two ways:

• From the Media section. Open Content → Media → Add media, choose the Kinescope type, paste the link, and save.
• From the media library dialog. If the core Media Library module is enabled, you can add a video right while selecting media: on the Kinescope type tab, paste the link and click Add. If no token is set, the dialog shows a warning about it.

To show videos from the media library in your content, add a Media field to the content type and allow your Kinescope media type in it.

Video details in media fields

With a token, the module gets video details that you can store in media fields. To do this, open the Field mapping section in the media type settings and map the details to fields.

The module saves posters to the kinescope_thumbs folder of the Drupal public file system.

Video in a popup

The Kinescope Popup module renders a poster with a link instead of the player. On click, the player opens in a window on top of the page.

1. Enable Kinescope Popup.
2. Choose the Kinescope popup display format:
   • for a Kinescope field in content — in the content type’s Manage display;
   • for videos from the media library — in Manage display of the Kinescope media type, for the Kinescope URL field. You don’t need to change the format of the Media field in the content.
3. In the format settings, set the Link text — the text next to the poster. The default is Play in popup.

The popup closes with the close button, the Esc key, or a click outside it. Playback stops when it closes.

The popup link is signed with the site key and is valid for one hour. Only roles with the View published content permission can open the popup.

Upgrading from 1.1 and 1.2

In versions 1.1.x and 1.2.x, Kinescope was a single module. Starting with 1.3, it is split into four and works only with Drupal 10 and 11.

1. Update the module:

   composer require drupal/kinescope:^1.3
   

2. Run the database updates: drush updb or the /update.php page. The update enables Kinescope Player and Kinescope Media for you.

3. Check the embed method on the Kinescope settings page.

4. Clear the cache:

   drush cr
   

Troubleshooting

The player does not show on the site. Check whether embedding of the video is restricted by domain. If it is, add your site’s domain to the allowed ones — see Restricting video access.

The title and description are not pulled in. Open Reports → Status report and check the Kinescope API token row. If the token is set, look at the Drupal log: on a 401 or 403 API response, the module writes a warning to the kinescope channel asking you to check the token. Until the token works, the module shows videos without API details.

The field does not accept the link. Make sure the link starts with https://kinescope.io/ and has no parameters after ?.

What’s next?

After you set up the module, we recommend:

1. Restrict video access — allow playback only on your site’s domain.
2. Set up content protection — turn on DRM encryption and watermarks.
3. Customize the player — match the player’s look to your brand.
4. Explore the IFrame API — control the player from JavaScript.

Questions about the module? Ask the developers in the project issue queue on drupal.org.