---
title: "Add a clip to the stinger library (the stinger source's playlist). Adding a file already in the library returns it unchanged. Upload the file first with the media API when it is not on the server yet."
method: POST
path: "/api/flows/{flow_id}/blocks/{block_id}/stinger/clips"
tags: ["flows"]
---

# Add a clip to the stinger library (the stinger source's playlist). Adding a file already in the library returns it unchanged. Upload the file first with the media API when it is not on the server yet.

`POST /api/flows/{flow_id}/blocks/{block_id}/stinger/clips`

## Request

- The document declares no server URL.
- Auth: none declared

## Path parameters

- `flow_id` string, required
- `block_id` string, required

## Request body

- StingerAddClipRequest: Add a clip to the stinger library.
  - `file` string, required: Path relative to the media directory (as the media API names files), an absolute path, or a URI.
  - `settings` StingerClipSettings: Per-clip stinger settings, stored on the clip's Media Player.
    - `beneath` 'cut' | 'mix': What a classic stinger does to the program at its cut point.
    - `cut_point_ms` integer, nullable: Classic: how far into the clip the program changes. `None` takes it from the clip: the frame where the graphic covers most, or where the matte crosses half way.
    - `invert_matte` boolean: Swap black and white in the matte.
    - `layout` 'auto' | 'classic' | 'side_by_side' | 'stacked' | 'mask_only': How a stinger clip lays out its graphic and matte.
    - `mix_ms` integer: Classic: length of the mix beneath, when `beneath` is `mix`.
    - `premultiplied` boolean: The graphic's colour is premultiplied by its alpha (After Effects' "Premultiplied (Matted)" export).

## Response `200`

The clip, as it plays here

- StingerClip: One playlist entry of the stinger source, as the mixer sees it.
  - `analysis_error` string, nullable: Why the clip's analysis failed, when it did. It is not retried until the file changes or the library is reloaded.
  - `cut_point_ms` integer, nullable: Effective cut point for a classic take.
  - `downgraded_from` 'classic' | 'track_matte' | 'mask_only': How a stinger switches the program beneath the clip.
  - `file` string, required: Playlist entry (path or URI).
  - `index` integer, required: Playlist index on the stinger source.
  - `info` StingerClipInfo: What analysing a clip found.
    - `analysis_ms` integer, required: How long the analysis took.
    - `cover_peak` number, float, required
    - `cover_peak_ms` integer, nullable: Where the graphic covers the largest part of the frame, and how much (0..1). Taken from the graphic's alpha.
    - `detected_layout` 'auto' | 'classic' | 'side_by_side' | 'stacked' | 'mask_only', required: How a stinger clip lays out its graphic and matte.
    - `duration_ms` integer, required: Length of the clip.
    - `framerate_den` integer, required
    - `framerate_num` integer, required: Frame rate as a fraction.
    - `frames` integer, required: Number of decoded frames.
    - `has_alpha` boolean, required: Whether the decoded frames carry an alpha channel.
    - `height` integer, required
    - `matte_end_ms` integer, nullable
    - `matte_midpoint_ms` integer, nullable: Where the matte first shows more of the new source than the old.
    - `matte_start_ms` integer, nullable: Where the matte starts and finishes moving: the first frame with any of the new source, and the first with all of it.
    - `width` integer, required: Decoded frame size of the whole clip.
  - `missing` boolean: The clip's file is not on disk (deleted or renamed since it was added). Only a local file can be missing.
  - `settings` StingerClipSettings, required: Per-clip stinger settings, stored on the clip's Media Player.
    - `beneath` 'cut' | 'mix': What a classic stinger does to the program at its cut point.
    - `cut_point_ms` integer, nullable: Classic: how far into the clip the program changes. `None` takes it from the clip: the frame where the graphic covers most, or where the matte crosses half way.
    - `invert_matte` boolean: Swap black and white in the matte.
    - `layout` 'auto' | 'classic' | 'side_by_side' | 'stacked' | 'mask_only': How a stinger clip lays out its graphic and matte.
    - `mix_ms` integer: Classic: length of the mix beneath, when `beneath` is `mix`.
    - `premultiplied` boolean: The graphic's colour is premultiplied by its alpha (After Effects' "Premultiplied (Matted)" export).
  - `variant` 'classic' | 'track_matte' | 'mask_only': How a stinger switches the program beneath the clip.

## Other responses

- `400`: Invalid request, or no such file

## Changes

- **2026-10-08** `2f2410c0296b`: 1 info
  - added the optional property `analysis_error` to the response with the `200` status
- **2026-10-08** `d13f12490670`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/eyevinn/apis/strom-api/changes/api/flows/:flow_id/blocks/:block_id/stinger/clips/post.md)

---

[API](https://skmtc.dev/eyevinn/apis/strom-api.md) - [All operations](https://skmtc.dev/eyevinn/apis/strom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/eyevinn/apis/strom-api/revisions/8cd4dbc44175?raw)