# Kinescope module for Drupal

> Kinescope module for Drupal 10 and 11: installation, API token, player embed methods, the Kinescope field, video in the media library and in a popup.

Source: https://docs.kinescope.com/integrations/integration-with-drupal/
Updated: 2026-10-19

If your site runs on Drupal, you can add Kinescope videos to your content with the [Kinescope](https://www.drupal.org/project/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](https://www.drupal.org/project/issues/kinescope).

> **Info:**
>
> The module does not upload videos to Kinescope. Upload the video in the [dashboard](https://app.kinescope.io), copy its link, and paste it into Drupal.

## 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.

| Module | What it does | When to enable |
| :--- | :--- | :--- |
| **Kinescope** | Settings and requests to the Kinescope API | Always |
| **Kinescope Player** | The Kinescope field type and player output | Always — without it, no video is shown |
| **Kinescope Media** | A Kinescope source for the Drupal media library. Requires the core Media module | If you keep videos in the media library |
| **Kinescope Popup** | Opens the player in a popup | If you want the player on top of the page |

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

   ```bash
   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**.

> **Info:**
>
> Drupal section and button names in this article are given for the English interface. Paths like `/admin/...` do not depend on the interface language.

## 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.

| | Without a token | With a token |
| :--- | :--- | :--- |
| Player on the page | Yes | Yes |
| Video name in the media library | `Kinescope: video ID` | The video title in Kinescope |
| Media library thumbnail | The poster at `https://kinescope.io/ID/poster.webp` | The poster from the video details in the API |
| Description, subtitle, duration | No | Yes |

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

To connect a token:

1. In [Kinescope](https://app.kinescope.io), open **Settings → API tokens** and create a token. Learn more about tokens in [General API rules](https://docs.kinescope.com/developer-guides/api-general-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`:

```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.

> **Warning:**
>
> An API token gives access to your Kinescope workspace. Do not publish it or share it with anyone.

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.

| Method | What the module renders |
| :--- | :--- |
| **Simple iframe embed** (default) | A plain `<iframe>` with no JavaScript — [simple embed](https://docs.kinescope.com/player-docs/embedding/simple-iframe-embed/) |
| **IFrame API (auto-connect)** | An `<iframe>` with the `enableIframeApi` parameter and the IFrame API script — [IFrame API auto-connect](https://docs.kinescope.com/player-docs/embedding/iframe-api-auto-connect/) |
| **Web Components (experimental)** | The `<kinescope-iframe-player>` element — [web components](https://docs.kinescope.com/player-docs/embedding/web-components/) |

**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](https://docs.kinescope.com/player-docs/embedding/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.

> **Warning:**
>
> Kinescope web components are experimental, so their API may change.

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

| Parameter | Default | Description |
| :--- | :--- | :--- |
| **Responsive** | On | The player fills the container width with a 16:9 aspect ratio |
| **Width**, **Height** | 640 × 480 | Player size in pixels. Ignored when **Responsive** is on |
| **Allow-list options** | `autoplay; fullscreen; picture-in-picture; encrypted-media; gyroscope; accelerometer; clipboard-write; screen-wake-lock;` | The value of the `<iframe>` `allow` attribute |

> **Warning:**
>
> Do not remove values from **Allow-list options**: without them, autoplay, fullscreen, Picture-in-Picture, and DRM may stop working.

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.

> **Warning:**
>
> The module does not support playlists — use links to individual videos.

## 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.

| Detail in Drupal | What it contains |
| :--- | :--- |
| **Duration** | Video duration in seconds |
| **Description** | Video description |
| **Subtitles** | The video subtitle — the `subtitle` field in the API, not a captions file |
| **Thumbnail URI** | Path to the saved poster |
| **Video URL** | Video link |

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:

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

   ```bash
   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](https://docs.kinescope.com/content-protection/access-restrictions/).

**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](https://docs.kinescope.com/content-protection/access-restrictions/)** — allow playback only on your site's domain.
2. **[Set up content protection](https://docs.kinescope.com/content-protection/)** — turn on DRM encryption and watermarks.
3. **[Customize the player](https://docs.kinescope.com/video-player/player-customization/)** — match the player's look to your brand.
4. **[Explore the IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api/)** — control the player from JavaScript.

Questions about the module? Ask the developers in the [project issue queue on drupal.org](https://www.drupal.org/project/issues/kinescope).