plycdn Video — libraries, encoding, the player and signed webhooks

Audience: developers who put video in front of their users through plycdn: courses, lectures, training, recorded and live events. A video library is a private storage bucket made for video. You upload a file once; plycdn encodes it into adaptive streaming at several qualities, makes a poster and a scrubbing strip, and serves it through signed links that only your backend can issue. Your users watch in a keyboard-operable, accessible player, and your backend hears about each video through signed webhooks. Going live, from an encoder or from a browser, is Live streaming.

Everything in the Storage guide about buckets (regions, names, delivery settings, signing keys, usage and the audit log) applies to libraries as well; this guide covers what is different. Library and bucket names share one namespace; a library is always private, so a deleted library's name is held for 90 days after its purge, as a private bucket's is, and then free. The wire contract is in the API reference ("Video libraries", "Videos", "Playback links", "Webhooks"), and installing the packages, the player and your authorizer are in the Integration guide ("Video").

Video has its own package on each platform (version 1.17.0), which builds on the storage ones (Plycdn.AspNetCore.Video depends on Plycdn.AspNetCore.Storage; the npm packages carry both entry points):

dotnet add package Plycdn.AspNetCore.Video --version 1.39.0 --source YOUR_PACKAGE_FEED_OR_FOLDER
npm install ./vendor/plycdn-angular-1.39.0.tgz     # @plycdn/angular/video, for an Angular frontend
npm install ./vendor/plycdn-react-1.39.0.tgz       # @plycdn/react/video, for a React frontend

Register it with services.AddPlycdnVideo(builder.Configuration), which also registers storage. Step-by-step setup for each platform: Storage & video with ASP.NET Core, with Angular and with React.

As with storage, everything is called from your backend except sending the bytes of an upload and watching, which happen in the browser. The browser never holds your API key, and a viewer's player never calls plycdn: it plays from plycdn.net links that your backend signs.

Which key. As with buckets, creating, changing (PATCH) or deleting a library, and creating, changing or deleting a webhook endpoint or rotating its secret, need an admin API key (a standard key is refused with admin_key_required, 403). Everything else here works with a standard key: adding, reading, changing and deleting videos, signing playback, listing endpoints and their deliveries, sending a test event and redelivering.

1Video libraries

A library is created in one region, like any bucket, and is always private:

POST /api/content/v1/libraries
{ "name": "acme-lectures", "region": "mumbai",
  "processing": { "ladder": [240, 360, 480, 720, 1080, 1440], "download": true } }

Leave processing out and the library uses your organization's video settings (Video settings for your organization).

The answer (202) is the Bucket shape from the Storage guide with kind: "video" and visibility: "private", plus processing, processingOrigins, usesOrganizationProcessing and videoCount. The library is creating while its storage and delivery are provisioned and active when ready, exactly as a bucket is; its hostname is {name}.plycdn.net (acme-lectures.plycdn.net).

What makes a library different from a files bucket:

  • Always private. Every file is reached through a signed link. visibility cannot be set or changed (validation_error, fields: [["body","visibility"]]), on /libraries or on /buckets.
  • Video only. Uploads are limited to video/*, and an upload never replaces a file. Those two rules cannot be widened. You can still cap the largest file with maxObjectBytes.
  • Four-hour links. Playback links last 4 hours by default (delivery.linkTtlSeconds: 14400) rather than a files bucket's 15 minutes. The player renews them long before they run out, so a lecture keeps playing for as long as someone watches (Playing). Every other delivery setting (allowed domains, referrer blocking, countries, IP binding, rate limit) works as in the Storage guide, Delivering.
  • processing says how new videos are encoded:
Setting Default Meaning
ladder [240, 360, 480, 720, 1080] The qualities made, by the video's short side: any of 240, 360, 480, 720, 1080, 1440, 2160, each once. Never above the source: a 720p recording gets 240 to 720 even when the ladder goes to 2160. A source whose short side is below 240 gets one quality at its own size. Portrait video keeps its orientation
keepOriginal true Keep the file you uploaded after encoding, for your own records or a later re-encode. It is never served
download false Also make an MP4 viewers can download (from the highest quality at or below 720p)
thumbnails true Make the scrubbing strip the player shows over the seek bar

A changed processing applies to videos encoded afterwards; videos already encoded keep what they have until you encode them again. GET /libraries lists your libraries (never your files buckets), and GET /libraries/{libraryId} reads one; a files bucket's id there answers library_not_found.

Changing a library. PATCH /libraries/{libraryId} takes delivery, processing, analytics and maxObjectBytes. As everywhere in storage, a field you leave out is unchanged. processing merges: {"processing": {"keepOriginal": false}} changes that one setting, and the library then has settings of its own. Every processing setting always has a value, so null on one of its fields is refused with validation_error (fields naming it); send the value you want. {"processing": null} is different: it makes the library use your organization's video settings again. On delivery settings null removes a setting as it does on a bucket (Storage guide, Delivering, "Changing settings"), with one difference: "linkTtlSeconds": null returns a library's links to 4 hours, the video default.

Delivery analytics. A library carries the same analytics setting as a bucket (switch it on, up to three breakdowns, a value ceiling) and an Analytics tab in the dashboard (a bucket's is under Monitoring); see Storage guide, Traffic breakdown. In .NET it is UpdateLibraryRequest.Analytics (and ClearAnalyticsCeiling). Playback links carry no tags (a request for one is refused with 422 validation_error), so break a library's traffic down by path or a query parameter.

Video settings for your organization

A library has its own settings or uses its organization's:

  • A library created without processing uses its organization's settings, and follows them when they change. A library created with processing has its own four settings; a setting you leave out takes the organization's value as it is when you save. Libraries made before organization settings existed keep the settings they have.
  • Set your organization's defaults with videoDefaults in the organization settings: ladder, keepOriginal, download and thumbnails, each optional. A setting left out, or null, is not set there.
  • A sub-organization uses its parent's video settings unless it sets its own. Its own can be higher or lower: a parent's setting is a default, never a limit. A parent that makes every video at up to 720p can have one sub-organization make 1080 and 2160 as well.
  • When a video is encoded, we use, in this order: the library's own settings, the library's organization, that organization's parent, then plycdn's defaults (the table above).
  • Every library answer says which it is. usesOrganizationProcessing is true when the library follows its organization, and processingOrigins names, for each setting, where its value comes from: library, organization, parent or default.

Changing a library's or an organization's settings affects videos encoded afterwards. A video already encoded keeps its qualities until you encode it again. A video says what it was encoded with in its encoding (Statuses).

Everything else is the bucket's. A library is a bucket, and these stay on the /buckets/{id} routes with the library's id: retry (a library whose provisioning failed), restore (within 7 days of deleting it), signing-profile and signing-key/rotate (Signing playback yourself), and listing its objects. DELETE /libraries/{libraryId} is the bucket's soft delete: nothing plays from that moment, and its videos are deleted with it. POST /buckets/{libraryId}/restore brings the library and its settings back within 7 days, but not its videos.

Plan limits. Video is a plan feature: without it, creating a library or a video answers not_included_in_plan, and GET /plan says what your plan includes. Libraries count towards your plan's bucket limit. Your plan also sets the longest video it accepts (6 hours unless your plan says otherwise); a longer one fails with video_too_long (Statuses).

A library taken down by plycdn ("suspended": true, see Takedowns in the Storage guide) plays nothing: creating videos in it and signing playback links answer 403 bucket_suspended, while listing, reading, changing its settings and deleting still work.

// Server: your backend, with the API key (PlycdnVideoApi, PlycdnStorageApi and PlycdnVideoSigner are injected)
var library = await plycdn.CreateLibraryAsync(organizationId, new CreateLibraryRequest("acme-lectures", "mumbai")
{
    Processing = new LibraryProcessing(Ladder: new[] { 240, 360, 480, 720, 1080, 1440 },
                                       KeepOriginal: true, Download: true, Thumbnails: true),
});
// library.Kind == "video", library.State == "creating"; library.Processing, library.VideoCount
var libraries = await plycdn.ListLibrariesAsync(organizationId);
// Browser: a library's id is the bucketId the upload component takes. Libraries themselves are
// created and changed from your server only.
// <plycdn-upload [bucketId]="libraryId" prefix="sources/" accept="video/*"></plycdn-upload>
const libraryId = course.libraryId;   // stored by your backend when it created the library

Make a video library searchable

Turn on search for a library and its videos become searchable by what is said and shown in them, and each result plays in the player at the moment that matched. In the dashboard: the library, Settings, Search ("uploads and live recordings"). From your server: UpdateBucketSearchAsync with the library's id, or search on PATCH /api/content/v1/libraries/{id}.

  • An uploaded video is made searchable once it is encoded; a live recording once it has finished.
  • Include past recordings (on by default, includePastRecordings): when you turn search on, recordings that finished before then are made searchable too. Videos you uploaded before are always included.
  • A video is read from its kept original, or else its MP4 download; with neither, it is skipped with keep the original or the MP4 download to make videos searchable.
  • A video identical to one uploaded from 1.18.0 on and already searchable anywhere in your account (the same original, or the same MP4 download) is made searchable from that work: it is not transcribed again and is ready soon after it is encoded. We recognise it by the checksum we take when it is uploaded, so there is nothing for you to send.
  • Deleting a video removes it from search at once. Charges, limits and the reasons a video is not made searchable are those of a bucket, including removed from search (a video you delete stays out of search) and skipped videos being checked again by themselves once their reason goes away (a protected stream's recording stays protected, so it stays skipped).
  • Videos, and the video.* events sent to your webhooks, carry a search field: its state, the reason and the assetId of the searchable file.

2Adding a video

There are two ways, and both end the same way: the video is queued, then encoded.

A. Your server creates the video, the browser sends the bytes. Best when your application already has a record for the lesson or recording: you get the video's id before a byte is sent.

POST /api/content/v1/libraries/{libraryId}/videos
{ "title": "Week 1: Introduction", "size": 734003200, "contentType": "video/mp4",
  "fileName": "week-1.mp4", "metadata": { "course": "physics-101" } }

The answer (201) is the video ("status": "uploading") with an upload: an ordinary upload session (Storage guide, Uploading) whose videoId is this video and whose key is sources/{videoId}.mp4 (the extension comes from fileName, or else from contentType). title is 1 to 200 characters; metadata is up to 50 keys of strings, numbers or booleans and at most 8 KiB as JSON, returned as you sent them; sha256 is optional, as on any upload. The call requires an Idempotency-Key header, which makes it safe to repeat (the .NET package sends one for you), as do POST /libraries and POST /webhooks. Hand upload to the browser; the browser sends the parts to their URLs and your backend completes the session, exactly as for any upload. Completing it moves the video to queued.

var created = await plycdn.CreateVideoAsync(organizationId, libraryId,
    new CreateVideoRequest(Title: "Week 1: Introduction", Size: fileSize, ContentType: "video/mp4",
                           Sha256: null, FileName: "week-1.mp4",
                           Metadata: new Dictionary<string, object> { ["course"] = "physics-101" }));
await lessons.SetVideoAsync(lessonId, created.Id);          // your own record
return Ok(created.Upload);                                   // to the browser: created.Upload.VideoId == created.Id

The browser packages' uploader carries on with a session it is given. Give it a session source whose "start" answers with the one your server created; everything else (parts, retries, pause, resume after a reload, renewing, completing through your backend) is the uploader's usual work:

// Angular (@plycdn/angular/storage); React is the same with createPlycdnClient(...) in place of client.asSessionApi()
import { PlycdnStorageClient, PlycdnUploader } from '@plycdn/angular/storage';

const session = await firstValueFrom(this.http.post<UploadSession>(`/api/lessons/${lessonId}/video`, { size: file.size }));
const api = this.client.asSessionApi();
const uploader = new PlycdnUploader({ ...api, startUpload: async () => session });
const stored = await uploader.upload(file, { bucketId: session.bucketId, key: session.key }).done;

If the upload is abandoned (aborted, or never completed within its 7 days), the video becomes failed with upload_abandoned.

B. The browser uploads into the library, and the video is created for you. Best for a simple "add a video" page: upload under sources/ in the library with the ordinary upload component, and completing the upload creates the video, titled after the file name (sources/week-2 intro.mp4 becomes "week-2 intro"). The completion answer (POST /uploads/{uploadId}/complete, which your backend relays) carries the new video's videoId; the video's sourceKey is the uploaded key, and its uploadId the upload's id. To bring in a whole folder, see Moving many videos in.

// Angular
// <plycdn-upload [bucketId]="libraryId" prefix="sources/" accept="video/*" (stored)="added($event)"></plycdn-upload>
// React
const upload = useUpload();
await upload.start(file, { bucketId: libraryId, key: `sources/${file.name}` });
// Server: find the video an upload created (or wait for the video.ready webhook, described under Webhooks)
var session = await storage.GetUploadAsync(organizationId, uploadId);   // PlycdnStorageApi; session.VideoId once completed
var video = await plycdn.GetVideoAsync(organizationId, session.VideoId!.Value);

A library accepts uploads under sources/, at any depth (sources/week-1.mp4, sources/2026/week-1.mp4; not week-1.mp4). Any other key is refused with validation_error, fields: [["body","key"]], when the upload is started. Once a video has been made from a key, uploading that key again is refused with video_source_exists (except after a video that never became ready failed with video_source_missing: then the new upload replaces it). Through the S3 and Azure endpoints that key stays listed in sources/, read-only, with the size and upload time of the file you sent (you can't download or delete it from there), so a copy run again (rclone copy --ignore-existing, aws s3 sync, azcopy copy --overwrite=false) skips it; a tool that sends it anyway gets video_source_exists for that file only. Everything else about uploads (part sizes, resuming, video/* only, the largest file) is as in the Storage guide, Uploading.

Reading, changing and deleting. GET /libraries/{libraryId}/videos lists a library's videos, newest first, a page at a time (status to filter, cursor, limit 1 to 200, default 50; sourceKey returns only the video made from that key, such as sources/2026/week-1.mp4). GET /videos/{videoId} reads one; your browser code can read one too, through your backend (Playing). PATCH /videos/{videoId} changes title and metadata (a new metadata replaces the old; leave a field out to keep it). DELETE /videos/{videoId} deletes a video at once and for good: every quality, image, download and the kept original are removed, and so is its source file under sources/; nothing plays from that moment, and its title and metadata are erased. Its id, source key, size and dates stay in our records, with the audit log entry, for billing and security for as long as your account exists. Unlike a library, a deleted video has no restore window. While the video's upload is being completed, DELETE answers 409 upload_not_open marked "retryable": true: ask again shortly.

3Statuses

{ "id": "…", "libraryId": "…", "title": "Week 1: Introduction", "status": "ready", "errorCode": null,
  "durationSeconds": 612.48, "width": 1920, "height": 1080, "hasAudio": true,
  "renditions": [ { "height": 240, "width": 426, "bandwidth": 524000 },
                  { "height": 1080, "width": 1920, "bandwidth": 5478000 } ],
  "captions": [], "poster": true, "thumbnails": true, "download": false,
  "encoding": { "ladder": [240, 360, 480, 720, 1080], "keepOriginal": true, "download": false, "thumbnails": true,
                "origins": { "ladder": "parent", "keepOriginal": "default", "download": "organization", "thumbnails": "default" } },
  "sourceKey": "sources/week-1.mp4", "originalKept": true, "storedBytes": 734003200,
  "encodingMinutes": 10.208, "disabled": false, "metadata": { "course": "physics-101" },
  "uploadId": "…", "createdAt": "…", "updatedAt": "…", "playableAt": "…", "readyAt": "…" }
status Meaning
live A live stream on air: the video is the stream, with liveInputId and live: true; when the stream ends it goes on to playable and ready as its recording (Recordings)
uploading Created by your server (Adding a video, A); the upload has not completed yet
queued The file is in; waiting for an encoder
encoding Being encoded
playable The lowest quality is ready and plays already; the others are still being made. Share the video now if you like: viewers get the full set of qualities as soon as it is ready
ready Every quality, the poster, the scrubbing strip and the download (when asked for) are ready
failed It will not play. errorCode says why

A video moves forward only: uploading → queued → encoding → playable → ready, or failed at any point (a live stream's video goes live → playable → ready); encoding a ready video again starts it from queued once more. renditions lists the qualities made (bandwidth in bits per second: the most any part of that quality needs, measured on what was made, so a quiet lecture's is far below a busy film's); poster, thumbnails and download say which of those files exist; storedBytes is everything the video holds in your library (qualities, images, download and the kept original).

encoding is what the video was encoded with: the four settings, and where each came from (library, organization, parent or default). It is null until encoding starts and for videos encoded before it was recorded. The qualities in renditions can be fewer than encoding.ladder: a quality above the video's own size is never made.

Encoding a video again

POST /api/content/v1/videos/{videoId}/reencode    # 202

Encodes a ready video again with the settings that apply now, for example after you raised your organization's qualities. It needs an admin key and the original kept (keepOriginal); without it the answer is 409 original_not_kept. A video that is not ready (other than one whose new encode failed, below), or that plycdn has taken down, answers 409 video_not_ready. The answer is the video, now queued. It keeps playing from its current qualities until the first new one is made, and then goes queued, encoding, playable, ready again, with the same webhook events. Encoding it again is charged encoding minutes like the first encode, as its own usage entry for that run.

If encoding it again fails, the video is not lost. It goes back to ready and keeps playing the qualities that are complete (renditions lists them), its original is kept, errorCode says what went wrong (the video.ready event carries it too), and that run is not charged. Encode it again once the cause is fixed; errorCode clears when it starts. In the rare case that no complete quality is left, the video becomes failed but keeps its original and its files, and you can encode it again the same way.

errorCode What went wrong What to do
video_unreadable The file could not be read as video: damaged, cut short, of zero length, not really the format its name says, or not a single video file (accepted: MP4, MOV, MKV, WebM, AVI, MPEG-TS, MPEG-PS, FLV, WMV/ASF, Ogg, MXF; playlists, image sequences and GIFs are not) Check that it plays on your own computer, export it as MP4 if it is another kind of file, then upload it again
video_no_video_stream The file has no picture: an audio recording, or an audio file named .mp4 Upload a video; for audio only, use a files bucket
video_too_long Longer than your plan allows Trim it, or ask us about a plan with longer videos
video_resolution_unsupported Its picture is smaller than 16 pixels or larger than 8192 pixels on a side Export it at an ordinary size
video_source_missing The uploaded file was deleted, or replaced by another upload to the same name, before encoding finished For a video that never became ready, upload it again to the same name: the new file makes a new video and the failed one is deleted
upload_abandoned The upload your server created (Adding a video, A) was aborted or expired before it completed Create the video again
encoding_failed Encoding failed on our side after every retry; nothing about your file is known to be wrong Upload it again; contact us if it repeats

Encoding minutes. Encoding is counted in minutes of source video: a 10-minute 12-second recording is 10.2 minutes whatever ladder it gets (the exact figure is the source's duration in seconds ÷ 60, to six decimal places, and it is the video's encodingMinutes). A video is counted when it becomes ready, and again each time you encode it again; a failed video is never counted. Encoding minutes appear in GET /usage and, per library, in usage by resource (Storage guide, Usage), each against the library that holds the video. A video that becomes ready after its month was closed is counted as late usage on the next statement, as described under "Usage by resource" in the API reference. What a video holds counts as storage of its library, like any other file.

A video taken down by plycdn shows "disabled": true and does not play (see Takedowns in the Storage guide), exactly like a file taken down: signing a playback link answers 404 video_not_found, and a link signed before answers 404 (its files are moved out of anywhere a link can reach). A library taken down whole answers like a bucket: 403 bucket_suspended. The audit log records video.disabled (reason in detail.reason) and video.reinstated if we reverse it.

var page = await plycdn.ListVideosAsync(organizationId, libraryId, status: "failed");
foreach (var failed in page.Items)
    logger.LogWarning("{Title} failed: {Code}", failed.Title, failed.ErrorCode);
// React: polls every 15 s while the video is uploading, queued, encoding or playable
const { data: video } = useVideo(videoId);
if (video?.status === 'failed') showMessage(video.errorCode);
// Angular: this.client.getVideo(videoId).subscribe(video => ...)

4Playing

The packages include a player for each framework. Give it the library and the video:

<!-- Angular (@plycdn/angular/video, PlycdnVideoModule) -->
<plycdn-player [libraryId]="lesson.libraryId" [videoId]="lesson.videoId" (statusChange)="onStatus($event)"></plycdn-player>
// React (@plycdn/react/video, inside <PlycdnProvider>)
<PlycdnPlayer libraryId={lesson.libraryId} videoId={lesson.videoId} onStatus={setStatus} />

Both show the poster, then play the best quality the viewer's connection allows (with a quality menu, "Auto" first), playback speed from 0.5× to 2×, captions, full screen, the scrubbing strip over the seek bar, and a download button when the video has a download. They take ttlSeconds (how long each playback link lasts; the library's link lifetime when left out) and resume (default on).

What the player needs from your backend. Two routes, served by PlycdnVideoController and PlycdnStorageController (Integration guide, "Video"), which ask your IPlycdnStorageAuthorizer first:

  • GET videos/{videoId}: the video record (title, status, captions, download), authorized as PlycdnOperation.GetVideo.
  • POST sign with { "bucketId": <libraryId>, "videoId": <videoId> }: a playback link, authorized as PlycdnOperation.WatchVideo.

The playback link your backend returns:

{ "url": "https://acme-lectures.plycdn.net/v/<videoId>/master.m3u8?token=HS256-…&expires=1790000000&token_path=%2Fv%2F<videoId>%2F",
  "nativeUrl": null, "expiresAt": "…",
  "posterUrl": "https://acme-lectures.plycdn.net/v/<videoId>/poster.jpg?token=…",
  "thumbnailsUrl": "https://acme-lectures.plycdn.net/v/<videoId>/thumbnails.vtt?token=…",
  "downloadUrl": null }

One link opens one video: every quality, segment and image under that video, and nothing of any other. A video can be signed once it is playable; before that /sign answers video_not_ready.

What to store, and your own domain. Keep the video's id in your own records, never a signed link (it expires). The video's playbackPaths gives the paths it plays from (playlist is /v/<videoId>/master.m3u8; poster, thumbnails and download once it has them), on any of the library's hostnames. To play on a hostname of yours, add it to the library as a custom domain and send "hostname": "video.example.com" to /sign or /playback-sessions (the signers' hostname option, the players' hostname input); every address in the answer is then on it. A hostname that isn't an active domain of that library is 409 domain_not_active; live links stay on the library's own hostname. Step by step: Store and sign on your domain.

Link renewal and key rotation. The player asks your backend for a fresh link at 80 % of the link's lifetime (measured from when it arrived, never from the viewer's clock) and carries on without a pause or a reload: a four-hour lecture plays through any number of renewals. If the delivery network refuses a link (after you rotated the library's signing key, for example) the player asks for a new one at once and carries on from the same moment. A stream whose address cannot be reached (the viewer's network, for example) is treated the same way, at most every 10 seconds. If three renewals in a row fail or are refused, it stops and says so (playback_link_failed) with a Try again button. A browser that can play neither form of the stream shows playback_unsupported. Your own page never has to handle either.

Resume. The player remembers where each viewer stopped, in the browser's own storage, and starts there next time (not in the first 5 seconds or the last 10, and nothing breaks where storage is blocked). Pass [resume]="false" / resume={false} to always start at the beginning.

A video that is still playable. The player plays the qualities that exist, checks the video every 15 seconds, and when it becomes ready reloads at the same moment so the viewer gets every quality.

Captions. A video's caption tracks appear in captions once captions are added to it, and the player lists them in its captions menu. Until then the captions button is shown disabled, labelled "Captions (none available)".

Keyboard. The player's controls are buttons you reach with Tab and operate with Enter or Space. While the player (or one of its controls) has focus:

Key Does
Space or k Play or pause
← / → Back or forward 5 seconds
j / l Back or forward 10 seconds
↑ / ↓ Volume up or down 10 %
m Mute or unmute
c Next caption track, then off
f Full screen
Home / End Start or end
0 to 9 Jump to 0 % to 90 % of the video
< / > Slower or faster

These are ignored while Ctrl, Cmd (Meta) or Alt is held, and while a text field, text area, list or editable element has focus, so they never get in the way of typing. On a focused button, Space and Enter press that button.

Accessibility. Every control has a label; the seek bar is a slider that reads its position in words ("1 minute 5 seconds of 10 minutes"); menus say whether they are open; changes (playing, paused, volume, speed, quality, captions, resuming) are announced politely to screen readers; focus is always visible; and animation is switched off for viewers who ask for reduced motion.

Your own player. usePlayback (React) and PlycdnPlaybackService (Angular) give you signed, self-renewing links to use with any player: src (the stream), nativeSrc (for browsers that play the stream natively; see Signing playback yourself), poster, thumbnails, download, expiresAt, loading, error and refresh(). src is undefined while a link is loading and shortly before it expires, and changes when it is renewed. With a streaming player library of your own (the example is generic; use your library's way of changing requests), pass the link's query on every request, and call refresh() when a request is refused with 403:

import { StreamPlayer } from './stream-player';             // your own player library
import { usePlayback, tokenQuery, withToken } from '@plycdn/react/video';

function MyPlayer({ libraryId, videoId }: { libraryId: string; videoId: string }) {
  const { src, poster, refresh } = usePlayback(libraryId, videoId);
  const ref = useRef<HTMLVideoElement>(null);
  const token = useRef('');
  if (src) token.current = tokenQuery(src);                  // the newest link's token
  const started = useRef<StreamPlayer>();
  useEffect(() => {
    if (!src || started.current || !ref.current) return;
    const origin = new URL(src).origin;
    const player = new StreamPlayer({ rewriteRequest: (url) => withToken(url, token.current, origin) });
    player.onError((e) => { if (e.status === 403) refresh(); });
    player.load(src);
    player.attach(ref.current);
    started.current = player;
    return () => { player.destroy(); started.current = undefined; };
  }, [src === undefined]);                                     // start once; later links only change the token
  return <video ref={ref} poster={poster} controls />;
}

A browser that plays the stream natively takes nativeSrc directly as a <video src>. When it changes, set the new src and restore the position:

const { nativeSrc } = usePlayback(libraryId, videoId);
// <video src={nativeSrc} onLoadedMetadata={e => { e.currentTarget.currentTime = savedPosition; }} />

nativeSrc is undefined wherever plycdn does not offer the native form (Signing playback yourself); use the stream with a player library there.

5Viewer watermark and player logo

Step by step, with code for each language: Viewer watermark and your logo.

A viewer watermark draws each viewer's own details over the video, so a screen recording or a phone filming the screen shows who it came from; the player logo sits in a corner of every video. Both are drawn by plycdn's players (React, Angular, the watch page and the dashboard) over the picture. Nothing is encoded or stored again, the logo is never a link, and both are included in every plan.

Where they are set. Your organization's brand (PUT /watch-brand, Account & security → Branding) holds watermark and playerLogo; every library uses them until it has its own. A library's watermark is its own settings, or null while it uses the brand (PATCH /libraries/{id} with {"watermark": {"mode": "brand"}} returns it to the brand), and its logo is {"mode": "brand"} or {"mode": "off"} (Video libraries → a library → Protection). A sub-organization uses its parent organization's until it saves a brand of its own. A library's effectivePlayer says what its viewers get now.

Watermark setting Values Default
mode off, show (plycdn's players draw it; other players still play) or require (only players that draw it can play) off
fields Any of name, email, phone, viewerId, ip, time, each once, in the order shown ["name", "email", "time"]
phoneMask true shows the last 4 digits only (•••• 2345) true
text Fixed text shown last, 1 to 60 characters, no line breaks, or null null
opacity 5 to 60 (percent) 25
size small, medium or large, relative to the video medium
color light, dark or auto auto
moveEverySeconds 10 to 300, or null (it stays put) 30
placement anywhere, or a list of top-left, top, top-right, left, centre, right, bottom-left, bottom, bottom-right anywhere
Player logo setting Values Default
enabled true or false (the image is the brand's logo, PUT /watch-brand/logo) false
position top-left, top-right, bottom-left or bottom-right top-right
size small, medium or large, a share of the video's width medium
opacity 20 to 100 (percent) 80
inset 0 to 64, pixels from the edges 16

A watermark in show or require with no fields and no text is refused (422 validation_error). Until the brand saves them, GET /watch-brand leaves watermark and playerLogo out, and these defaults apply.

Who is watching. Your server passes the viewer's details when it starts the playback session: watermark on POST /playback-sessions (name, email, phone, viewerId, each plain text up to 1,000 characters, and an optional look that changes opacity, size, color, moveEverySeconds or placement for this viewer). The server packages' sign route asks your hook (PlaybackWatermarkFor, playbackWatermarkFor, playback_watermark_for). A detail the library shows but your server didn't pass is left out, never shown empty, so a viewer with no details sees the date and time and the fixed text. ip is shown only when the session has the viewer's address (ip, which the packages' route passes for libraries that bind links to it; on a library that shows ip without binding, it is used for the watermark only). time is the viewer's own local date and time, drawn by the player and not checked. The details are never stored or logged: they ride in the session's answer and are checked by a fingerprint on renewal.

What a session answers. When the library shows something, the playback session's answer gains:

"watermark": { "mode": "require", "lines": ["Asha Rao", "[email protected]", "Example Academy"], "timeAt": 2,
               "look": { "opacity": 25, "size": "medium", "color": "auto" }, "moveEverySeconds": 30, "placement": "anywhere",
               "proof": { "key": "…", "everySeconds": 60 } },
"logo": { "url": "https://watch.plycdn.com/api/watch/brand/…/logo?v=2", "position": "top-right", "size": "medium", "opacity": 80, "inset": 16 }

lines are plain text, each at most 80 characters (a longer one ends with "…"), to draw as text and never as markup. timeAt is where the viewer's date and time goes (null without time). proof is there only for require.

Require. A library that requires the watermark plays through playback sessions only, like serial playback:

  • Sessions last at most 600 seconds (a shorter ttlSeconds is kept) and answer sessionId, renewBy (at 80 % of the lifetime), pass, progressUrl and progressIntervalSeconds: 60, with nativeUrl and downloadUrl null.
  • watermark is required on every session: send {} when you have no details. Without it the answer is 409 watermark_required, and so is POST /sign with a videoId of the library.
  • The player checks in on progressUrl with "watermark": {"state": "present" | "tampered", "proof": "<proof.key>"}. A check-in without it, with tampered or with a wrong proof is counted against the session.
  • The player renews with a new session before renewBy: continues (the current sessionId) and watermarkProof (its proof.key), with the same viewer details and resumeId. A proof is good for one renewal. A wrong one answers 403 watermark_proof_invalid; a session whose check-ins were counted twice answers 403 watermark_tampered (the count carries over renewals and, for the same resumeId, over fresh sessions for an hour); a renewal more than 120 seconds after the session ended answers 410 playback_session_expired, and only then does the player start a new session.
  • The library's signing profile carries "watermarkRequired": true and "serial": true, so the server packages' signers refuse to sign plain links for it (watermark_required, or serial_playback_requires_session in older packages). Switching the requirement on or off sends signing_profile.changed with reason watermark_changed. Links already given out keep playing until they expire.
  • Our current players play it in Chrome, Edge, Firefox and Safari on computers, on Android, and on iPhone and iPad from iOS 17.1. The iPhone's own full-screen player, picture-in-picture and casting are not used while the watermark is drawn.
  • The players put the watermark back when it is removed, hidden, shrunk or moved, and pause playback after three times in a minute. A determined developer can still build a player that plays without drawing it; this stops ordinary screen recording, phone filming and casual tampering.

Live and share links. The live player and the watch page draw the logo and a watermark of the fixed text and the date and time (mode: "show", no viewer details, no proof): it is not required on live streams or on a share link's page, which anyone with the link may open.

A player of your own. PlycdnWatermark.Render(session) (ASP.NET Core) and PlycdnWatermark.render(session) (Node.js, Python) read what to draw, with LinesAt/linesAt/lines_at for the time and CheckIn/checkIn/check_in for the check-in body; PlycdnWatermark.Renewal/renewal builds the renewal request. In the browser, PlayerMark draws and defends the marks, and a request to your backend's sign route says "watermark": "drawn".

6Serial playback

Step by step, with code for each language: Serial playback guide.

For courses, compliance training and anything else that must be watched in order. Turn on serial playback for a library and its viewers can't skip ahead: no viewer can reach a moment of a video sooner than that much time after they started watching it (minute 20 no sooner than 20 minutes in), counted across every visit with the same resumeId. It holds whatever runs in the viewer's browser: an extension, a changed player, a copied link or a guessed address. Viewers can still go back to anything they have watched, pause, and change quality.

Time paused, or a tab left playing, counts as time watched. Serial playback can't tell whether a person is looking at the screen, and it can't stop screen recording: pair it with attention monitoring if you need proof that someone watched. A changed player can load up to 18 seconds ahead of the watched point; plycdn's players never show it.

Serial playback is part of the Growth and Enterprise plans (serial_playback). Turn it on when you create a library ("playback": {"serial": true}) or later with PATCH /libraries/{id}, or with Serial playback in the library's settings on the dashboard. Turning it on counts as a change of the library's signing keys, so it can answer 429 rate_limited (wait for Retry-After), and it answers 409 serial_playback_busy, with Retry-After, while the library is being moved to another delivery network: try again after the wait. A library made before plycdn links can't turn it on yet and answers serial_playback_needs_plycdn_links: contact support and we will move it onto serial playback, or create a new library with serial playback on and add its videos there.

Playing a serial video

With plycdn's server packages nothing changes in your frontend: the players' sign route starts a session for the viewer by itself. Name the viewer on your server (PlaybackResumeIdFor, playbackResumeIdFor, playback_resume_id_for) with your own id for them, such as a learner or a seat, never an email address. The browser never names the viewer.

From your own code, start a session with your key (StartPlaybackAsync, startPlayback, start_playback):

POST /api/content/v1/playback-sessions   {"bucketId": "<library id>", "videoId": "<video id>", "resumeId": "learner-42"}

The answer is a playback link with serial: true, watchedSeconds (where this viewer is), durationSeconds, completed, pass and progressUrl. Give url to any video player, the ones built into phones included: everything it needs is in the address. If a page of your own plays it in its own video element, add crossorigin to that element (<video crossorigin controls>) before you give it the address: some browsers play a session only then, and every session needs it, with serial playback on or off. With a resumeId, the position plycdn has recorded for that viewer decides where playback resumes: a session starts there, never where a browser asks, so a browser can't choose a later start. On a library without serial playback the same call answers the ordinary links with serial: false; when it names the viewer (a resumeId) it also starts a session that records watch time, with pass, progressUrl and progressIntervalSeconds: 120 (the players save every two minutes there), so one call works everywhere. Without a resumeId there is no session. POST /sign for a video of a serial library answers serial_playback_requires_session, and so do the server packages' own signers.

The players save the viewer's position to progressUrl every minute (progressIntervalSeconds) while playing, on pause, at the end and when the page is hidden. A player of your own posts {"pass": "<pass>", "position": <seconds>, "played": <seconds>} there as text/plain. plycdn keeps no more than the time that has really passed since the session started, so a claimed position never moves anyone ahead. A session lasts the library's link lifetime (or ttlSeconds); the players start a new one before it ends, and it carries on from the saved progress. Scrubbing previews and the MP4 download aren't offered in a session, and a live stream's recording can't be played in a serial library (serial_playback_unavailable).

Every player also reports where it is (onProgress in React, (progress) in Angular, with played, the seconds this session has been playing), in every library, serial or not. These positions come from the browser and are for convenience; in a library with serial playback, the watchedSeconds plycdn keeps for the viewer's resumeId is the one to trust, and the one to use for anything you enforce.

Viewer progress

GET /api/content/v1/playback-progress?bucketId=…&videoId=…&resumeId=…
GET /api/content/v1/playback-progress?bucketId=…&resumeId=…
DELETE /api/content/v1/playback-progress?bucketId=…&videoId=…&resumeId=…

The first answers one video (watchedSeconds, durationSeconds, completed, completedAt, updatedAt), or progress_not_found before the viewer starts it; the second, every video of the library they have started, a page at a time (GetPlaybackProgressAsync, ListPlaybackProgressAsync, ResetPlaybackProgressAsync); the third starts them over for a retake: their next session starts at the beginning, and a tab still open from before saves nothing. A video counts as complete within its last six seconds. The answers also carry watchTimeSeconds and firstWatchedAt (see Watch time); starting a viewer over leaves their watch time as it was. The dashboard's video page looks a viewer up and starts them over, in every library.

7Watch time

Step by step: Watch time guide.

How long did each learner, employee, member, patient or customer really watch? Name the viewer on your server with your own id (PlaybackResumeIdFor, playbackResumeIdFor, playback_resume_id_for; never an email address) and plycdn keeps their watch time in every video library, serial or not: the time the video was actually playing. Pauses don't count, watching again does, and an hour at double speed counts as an hour. It is separate from watchedSeconds, the furthest point the viewer reached. Viewers you don't name are not tracked.

The players add the seconds they have been playing to the position they already save: every two minutes in an ordinary library, every minute with serial playback, and on pause, at the end and when the page is hidden. There is no extra request. A session's total never exceeds the time that has really passed since it started, so a changed player can't inflate it. The totals are batched, so a viewer still watching can be a few minutes behind.

Read it per viewer and per video with GET /libraries/{libraryId}/watch-time (any API key; GetWatchTimeReportAsync, getWatchTimeReport, get_watch_time_report; a CSV with DownloadWatchTimeCsvAsync, downloadWatchTimeCsv, download_watch_time_csv), with a date range of up to 366 days: see Watch time report. Each viewer's own figures are on their progress (watchTimeSeconds, firstWatchedAt). In the dashboard, Video streaming → Watch time (or a library's Watch time tab) for the totals, the table by viewer or by video, a viewer's videos and Download CSV; a video's Viewer progress shows one viewer's watch time and when they first watched. Watch time is in every plan.

8Signing playback yourself

PlycdnVideoSigner.SignVideoAsync (Plycdn.AspNetCore.Video) signs playback links in your own process, from the library's cached signing profile, with no request to plycdn per link:

var link = await signer.SignVideoAsync(organizationId, libraryId, videoId, ttl: TimeSpan.FromHours(4));
// link.Url, link.NativeUrl, link.ExpiresAt, link.PosterUrl, link.ThumbnailsUrl, link.DownloadUrl

Signed locally, PosterUrl, ThumbnailsUrl and DownloadUrl are always filled in: the signer does not know which of those files a video has, so check the video's poster, thumbnails and download before showing them. Signing locally also does not check that the video exists or can play yet; ask POST /sign (which does, and answers video_not_ready or video_not_found) when that matters.

A link signed locally never carries protection. For the recording of a protected live stream, sign through plycdn: PlycdnVideoSigner.SignVideoFromPlycdnAsync takes the same arguments and always asks POST /sign, so its answer carries protection when the recording has it.

A library's signing profile (GET /buckets/{libraryId}/signing-profile) carries two fields files buckets do not use:

{ "bucketId": "…", "scheme": "pl1", "keyId": "k2", "key": "…", "hostname": "acme-lectures.plycdn.net",
  "hostnames": ["acme-lectures.plycdn.net"],
  "defaultTtlSeconds": 14400, "ipBinding": false, "directoryScheme": "pl1d", "pathTokens": false }

directoryScheme is pl1d for a library with plycdn links and ps3 for a library made before them (null on a files bucket); both are described below. pathTokens says whether plycdn offers the path form of a link, which browsers that play the stream natively need; only when it is true does a playback link carry a nativeUrl. Where it is false, nativeUrl is null and the player uses its built-in engine in every browser that supports it, which is every current browser, Safari included.

The ps3 scheme. A directory token covers every file under one video's directory:

token_path = "/v/" + videoId + "/"                                 # always ends with a slash
expires    = now + ttl                                             # Unix seconds
ip_bytes   = b""                                                   # no IP binding
           | the 4 bytes of the IPv4 address                       # IPv4 binding
message    = utf8(token_path) + utf8(str(expires)) + ip_bytes + utf8("token_path=" + token_path)
token      = "HS256-" + ("1-" if ip else "") + base64url_nopad( HMAC-SHA256(key = utf8(key), msg = message) )

query form: https://{host}{token_path}{file}?token={token}&expires={expires}&token_path={percent_encode(token_path)}
path form:  https://{host}/_t/{token}/{expires}{token_path}{file}

file is master.m3u8 for the stream, poster.jpg, thumbnails.vtt or download.mp4; every other file of the video is reached from those, with the same token. percent_encode encodes every reserved character, so / becomes %2F. IP binding works as in the Storage guide ("Signing links yourself"): bind the viewer's IPv4 address. key is the library's signing key from the profile.

The pl1d scheme (libraries with plycdn links) is ps3 with the prefix "PL1-" in place of "HS256-", signed with the library's key from the profile. The query form and the path form are the same. A pl1d link keeps working whatever changes on our side. The published vectors (plycdn-signing-vectors-pl1.json, directory) include both forms. Worked example with the test key pl1-test-key-0123456789abcdefghijklmnopqrstu (a test vector, never a real key), video 0b6f1c3e-2d4a-4f5b-9c8d-7e6f5a4b3c2d, expires = 1790000000, no IP binding:

token_path: /v/0b6f1c3e-2d4a-4f5b-9c8d-7e6f5a4b3c2d/
message:    /v/0b6f1c3e-2d4a-4f5b-9c8d-7e6f5a4b3c2d/1790000000token_path=/v/0b6f1c3e-2d4a-4f5b-9c8d-7e6f5a4b3c2d/
url:        https://acme-lectures.plycdn.net/v/0b6f1c3e-2d4a-4f5b-9c8d-7e6f5a4b3c2d/master.m3u8?token=PL1-pzD4t8UtapvUKLEA9E028eu8984nNniHCEwKgM3ZIjo&expires=1790000000&token_path=%2Fv%2F0b6f1c3e-2d4a-4f5b-9c8d-7e6f5a4b3c2d%2F

On a library that has ps3, sign with HS256- as shown next. A library whose CORS allows credentials keeps ps3 for the reason given under CORS in the Storage guide.

Worked example: the message for the published test key SecurityKey (a test vector, never a real key), video 2f1c1a52-8a38-4b8e-9d7e-7a0e2f3c9b11, expires = 1598024587, no IP binding:

token_path: /v/2f1c1a52-8a38-4b8e-9d7e-7a0e2f3c9b11/
message:    /v/2f1c1a52-8a38-4b8e-9d7e-7a0e2f3c9b11/1598024587token_path=/v/2f1c1a52-8a38-4b8e-9d7e-7a0e2f3c9b11/
url:        https://acme-lectures.plycdn.net/v/2f1c1a52-8a38-4b8e-9d7e-7a0e2f3c9b11/master.m3u8?token=HS256-fzus3wjZCDu0oHovggTxjnMNr4a9_i3oaAbp_qCqlaI&expires=1598024587&token_path=%2Fv%2F2f1c1a52-8a38-4b8e-9d7e-7a0e2f3c9b11%2F

A token never depends on the host. Test your own signer against this worked example. The .NET package's signer produces exactly this token, including for IP-bound links.

// TypeScript on your server (Node): the signing key never reaches a browser
import { createHmac } from 'node:crypto';

export function signVideo(key: string, host: string, videoId: string, file: string, expires: number): string {
  const tokenPath = `/v/${videoId}/`;
  const mac = createHmac('sha256', key).update(`${tokenPath}${expires}token_path=${tokenPath}`).digest('base64url');
  return `https://${host}${tokenPath}${file}?token=HS256-${mac}&expires=${expires}&token_path=${encodeURIComponent(tokenPath)}`;
}

A signed playback link must be used as issued: the player adds the same token, expires and token_path to each file it fetches under the video's directory, and changes nothing else.

9Content Security Policy

The player reads the stream's playlists and segments with the browser's own requests, so a strict Content Security Policy needs:

connect-src https://*.plycdn.net;                 /* playlists, segments, the scrubbing map */
media-src   blob: https://*.plycdn.net;           /* the stream, and the native form */
img-src     https://*.plycdn.net https://watch.plycdn.com;   /* poster and scrubbing images, and your player logo */
worker-src  blob:;                                /* the player's stream decoder runs in a worker */

Watching a stream in real-time mode, and going live from the browser, also contact https://*.live.plycdn.com (the address your sign route and publish token answers carry), so add it to connect-src where you use them.

plus, for uploads, Storage's connect-src https://{label}.upload.plycdn.com (for example https://in-mum.upload.plycdn.com). A library's delivery answers these cross-origin reads for you (it adds the CORS headers to m3u8, m4s, mp4, vtt and jpg files), so there is nothing to set in the library's cors settings, for the plycdn player or for a player of your own. You can narrow https://*.plycdn.net to your libraries' own hostnames (https://acme-lectures.plycdn.net).

app.Use(async (context, next) =>
{
    context.Response.Headers["Content-Security-Policy"] =
        "default-src 'self'; connect-src 'self' https://acme-lectures.plycdn.net https://in-mum.upload.plycdn.com; " +
        "media-src blob: https://acme-lectures.plycdn.net; img-src 'self' https://acme-lectures.plycdn.net https://watch.plycdn.com; worker-src blob:";
    await next();
});
// A Node server in front of your frontend
res.setHeader('Content-Security-Policy', [
  "default-src 'self'",
  "connect-src 'self' https://acme-lectures.plycdn.net https://in-mum.upload.plycdn.com",
  'media-src blob: https://acme-lectures.plycdn.net',
  "img-src 'self' https://acme-lectures.plycdn.net https://watch.plycdn.com",
  'worker-src blob:',
].join('; '));

10Live streaming

Step by step, from your first stream to recordings and restreaming: Live streaming guide. In the dashboard, live streams have their own place: Live streaming → Live streams.

Go live from any encoder or from a web page, and let viewers watch within a few seconds, or in under a second for an interactive audience. Each broadcast is recorded as an ordinary video in the same library, at the same address, with no second encode. Typical uses are conferences and product launches, sports and tournaments, live selling, company town halls, worship services and training sessions.

The words used here:

  • A live input is a standing place to broadcast to, in one video library: "Main stage", "Studio 2", "Sunday service". It has a stream key (the secret an encoder publishes with) and its own settings.
  • A stream is one continuous broadcast on an input, from the first picture until it ends. A stream that drops and comes back inside the reconnect window is still the same stream.
  • A recording is the video the stream becomes when it ends. A stream's id is its recording's video id.
  • A publish token is a short-lived credential your server hands to one browser so that it can go live, without the browser ever seeing a stream key.
  • Broadcast and real-time are the two ways viewers receive a stream (below).

Live streaming is included in every plan that includes video, and is priced by the minute of streaming and, for real-time viewing, by viewer-minute (Plans and prices). Until it is switched on for your service, every live route answers feature_not_available (404) and the live player and broadcaster components show nothing (their state event still reports the code); a plan without it answers feature_not_in_plan (403). GET /regions says which regions offer live streaming ("live": true). The wire contract is in the API reference.

Which key. Creating, changing and deleting an input, showing or replacing its stream key, making publish tokens, disabling and enabling an input, ending a stream, reading streams and their viewers and health, restream destinations, ad breaks and share links, the watch page brand and watch domains need an admin API key, and so belong in your backend (a standard key is refused with admin_key_required, 403). A standard key can read one input (it then sees only what a page may see: the input's id, state and delivery mode and the running stream's id, state and times, never an address, key or setting), read a stream's captions (GET /streams/{id}/captions) and ask for playback links.

What your plan includes. Live captions, restreaming and ad insertion come with a plan that includes them (live_captions, live_restream and live_ads in GET /plan; Billing & usage → Usage → Plan in the dashboard), and content protection with a protection setup on your account; contact us to add one. Without it the settings and routes that belong to it answer the codes in Live errors, and the dashboard says it is available on request instead of offering it. They are not part of the prices below.

Your first stream, step by step

From nothing to a live page with a replay, in order. Each step says where it is explained in full.

  1. Make a live input in a video library: in the dashboard under Live streaming → Live streams → New live stream (with a new library made for it, or in one you have), or from your backend with POST /libraries/{libraryId}/live-inputs (Live inputs). Choose broadcast (a few seconds behind, any audience size) or realtime (under a second) as its delivery. Keep the stream key it shows in your secret store.
  2. Connect your encoder. Copy the RTMPS address from the input's page (or ingest.rtmps) and put the stream key into it where {streamKey} stands. In OBS Studio, Settings → Stream → Service: Custom…, paste the whole address into Server, leave Stream Key empty and choose Start Streaming (Going live from an encoder).
    • RTMP is the same with the ingest.rtmp address, for encoders that cannot encrypt.
    • SRT for venues and mobile links: in OBS choose Custom… and paste the whole ingest.srt address, key in place, into Server (it starts srt://). A hardware encoder takes it in its SRT destination field.
  3. Watch it go On air. The input's state becomes connected as soon as the encoder is accepted and live as the first picture goes out, within seconds; the dashboard page updates by itself, and your backend hears live.connected then live.started (Live webhooks). An H.264 picture (what RTMP, RTMPS and SRT encoders send, and browsers) is on air in its original quality within seconds; the other qualities of the input's quality are added by themselves about a minute later. Meanwhile the stream says "qualitiesComing": true and the dashboard shows On air · more qualities coming; players add the new qualities without the page being reloaded. The minutes before that are counted in the original quality's meter, and the recording covers the stream from its first second.
  4. Or go live from a web page. Your backend registers an authorizer (IPlycdnLiveAuthorizer in .NET), the page shows <plycdn-live-broadcaster> or <LiveBroadcaster>, and the signed-in user presses Go live: the browser gets a publish token, never the key (Going live from the browser).
  5. Sign playback links on your backend. Your backend decides who may watch and asks POST /sign with the liveInputId (PlycdnVideoSigner.SignLiveAsync in .NET) (Watching a live stream). Links last 15 minutes by default and the player renews them.
  6. Put the player on your page. <plycdn-live-player> (Angular) or <LivePlayer> (React) signs through your backend, plays at the lowest delay it can, shows Waiting for the stream to start until the stream is on air, and plays the recording in the same place when it ends. For real-time viewing, leave the mode to the input (or pass mode="realtime" on a real-time input): the player connects in real time and falls back to the broadcast stream by itself when the audience cap is reached.
  7. Optional, before you go live: turn on captions (Live captions), a rewind window (Rewinding), searchable recordings (Searchable recordings), or add restream destinations (Restreaming). Captions, restreaming, ads and protection come with the plans that include them.
  8. End the stream. Stop the encoder (the stream ends when the reconnect window passes), or end it at once from the dashboard's End stream button or POST /live-inputs/{id}/end (EndStreamAsync in .NET) (Reconnecting and ending).
  9. Use the replay. Unless you turned recording off, the stream becomes a video with the same id: live.ended carries it, then video.playable and video.ready follow, and the link that played the live stream plays the replay (Recordings).
  10. When something is refused, the answer carries a code from Live errors; the dashboard shows the same codes in words.

Live inputs

Create an input in a video library (admin key). The answer carries the stream key, shown here, when you replace it and when an administrator asks for it again; keep it in your secret store.

POST /api/content/v1/libraries/{libraryId}/live-inputs        # 201
{ "name": "Main stage", "settings": { "delivery": "broadcast", "quality": "hd" }, "metadata": { "event": "keynote" } }
{ "id": "5f0e…", "libraryId": "…", "name": "Main stage", "state": "idle",
  "streamKeyPrefix": "live_Ab3D", "streamKey": "live_Ab3D…",
  "ingest": { "rtmps": "rtmps://in-mum.live.plycdn.com:443/5f0e…?key={streamKey}",
              "rtmp":  "rtmp://in-mum.live.plycdn.com:1935/5f0e…?key={streamKey}",
              "srt":   "srt://in-mum.live.plycdn.com:9000?streamid=publish:5f0e…:live:{streamKey}&latency=120",
              "whip":  "https://whip-in-mum.live.plycdn.com/5f0e…/whip" },
  "settings": { "delivery": "broadcast", "quality": "hd", "passthrough": true, "recording": true,
                "reconnectWindowSeconds": 60, "maxDurationSeconds": 86400, "latencyTarget": "lowest" },
  "stream": null, "metadata": { "event": "keynote" }, "createdAt": "…", "updatedAt": "…" }
var input = await videos.CreateLiveInputAsync(orgId, library.Id, new CreateLiveInputRequest("Main stage",
    new LiveInputSettings { Delivery = DeliveryMode.Broadcast, Quality = "hd" }));
await secrets.SaveAsync(quot;plycdn-live-{input.Id}", input.StreamKey);      // shown here, and when revealed or replaced

The settings, all optional (what you leave out takes the default; a change applies from the next stream):

Setting Values Default What it does
delivery broadcast, realtime broadcast How viewers receive the stream (choosing a delivery mode)
quality source, sd, hd, fhd hd The top quality offered to viewers: sd up to 480p, hd up to 720p, fhd up to 1080p, source your picture as it arrives, unchanged. Lower qualities are made for viewers on weaker connections. Never above what the encoder sends
passthrough true, false true Also offer your encoder's own picture as the top quality, as it is, when it is H.264 (Use the source picture when it is H.264 under Quality in the dashboard). quality source needs it: a stream whose picture can't be passed on then ends with input_unsupported (Passthrough)
recording true, false true Keep each stream as a video in the library (recordings)
reconnectWindowSeconds 0 to 600 60 How long a dropped encoder may take to come back and carry on the same stream. 0 ends the stream at once
maxDurationSeconds 60 up to your cap 86400 The longest one stream runs; at this length it ends with max_duration_reached
latencyTarget lowest, balanced lowest For broadcast: as close to live as possible, or a little further back and steadier on weak networks
backupIngest true, false false A second set of publishing addresses for a second encoder, so the stream survives one encoder or link failing (backup ingest). A plan option
redundantTranscoding true, false false A standby copy of the processing of each stream that takes over at once if the first is lost (backup ingest). A plan option
captions { "enabled", "languages", "mode" } off Captions made from the stream's speech as it is spoken (live captions). When your plan includes them
dvrWindowSeconds 0 to 7,200 0 How far back a viewer may seek in the running stream; 0 keeps the short live window (rewinding)
indexRecording true, false false Make each recording searchable when it is ready (searchable recordings)
protection { "provider", "options" } off Encrypt the stream and its recording; viewers' players ask for a key (content protection). With a protection setup on your account
ads { "enabled", "vmapUrl", "vastUrl", "slate", "personalised" } off Insert ads into the stream during ad breaks (ad breaks). When your plan includes ads

backupIngest, redundantTranscoding, captions and dvrWindowSeconds are fixed while a stream is running: changing one then answers 409 live_input_busy; change it between streams. A setting your plan does not include, turned on, answers 409 live_setting_not_in_plan with detail.setting naming it. Two settings cannot be on together: ads with protection, and ads with a DVR window (settings that cannot be combined). Streaming to other platforms (restreaming) is not a setting but a list of destinations on the input (restreaming).

The quality you choose is also how the stream is counted: a stream is billed per minute at the price of its top quality, source being the lowest (Plans and prices).

GET /live-inputs/{id} shows an input; GET /libraries/{libraryId}/live-inputs lists a library's (each with the stream running on it); PATCH /live-inputs/{id} renames it, changes settings (only the ones you send) or replaces its metadata; POST /live-inputs/{id}/disable stops it taking streams and ends the one running (input_disabled), POST /live-inputs/{id}/enable allows it again; DELETE /live-inputs/{id} deletes an input that is not streaming (live_input_busy while a stream runs: end it first). Its recordings stay as videos. An input's state is idle, connected (an encoder is publishing and viewers cannot watch yet), live or disabled. metadata holds up to 50 keys of strings, numbers or booleans, at most 8 KiB.

The stream key

The stream key (live_ and 40 characters) is the secret an encoder publishes with. It is not shown in lists. Replace it any time with POST /live-inputs/{id}/stream-key (the old key stops working at once, and unused publish tokens for the input stop with it); GET /live-inputs/{id}/stream-key shows the current key again, and every reveal is recorded in the audit log with who asked. Both answers are never cached. Treat it like a password: keep it out of source control, logs and any page a browser loads. A browser never needs it: it goes live with a publish token.

An input takes one publisher at a time: a second encoder with the same key is refused while the first is connected (stream_key_in_use). More than ten wrong keys or tokens a minute from one address block that address for ten minutes (rate_limited, 429, with Retry-After).

Going live from an encoder

Any standard encoder or broadcasting application works: OBS Studio, vMix, Wirecast, a hardware encoder, a camera with a streaming mode, a phone app. Use the address that matches what your encoder speaks. The input's id is already in it; replace {streamKey} with the stream key:

Protocol Address Notes
RTMPS ingest.rtmps (rtmps://{host}:443/{inputId}?key={streamKey}) Encrypted. Prefer this wherever the encoder supports it
RTMP ingest.rtmp (rtmp://{host}:1935/{inputId}?key={streamKey}) For encoders without encryption
SRT ingest.srt (srt://{host}:9000?streamid=publish:{inputId}:live:{streamKey}&latency=120) For unreliable networks (venues, mobile links, long distance); the delay it allows for retransmission is latency=120 (milliseconds): raise it on a poor link

In OBS Studio: open Settings → Stream, set Service to Custom…, paste the whole RTMPS address, with the key in place, into Server, leave Stream Key empty, then choose Start Streaming. Under Settings → Output choose:

  • video encoder H.264 (the software encoder or your graphics card's H.264 encoder), rate control CBR, a bitrate that your uplink carries with room to spare (about 4,500 to 6,000 kbps for 1080p30, 2,500 to 4,000 for 720p30);
  • keyframe interval 1 or 2 seconds (a shorter interval lets viewers start sooner and keeps delay low);
  • audio AAC, 128 kbps, 48 kHz.

Any other encoder: H.264 video, AAC audio, constant bitrate, a keyframe every 1 to 2 seconds, up to 1080p and 12,000 kbps (the defaults of the safety caps, which can be raised), at up to 60 frames a second (a fixed limit). Put the whole address, with the key in place, into the encoder's server or destination field (for SRT, its SRT destination field).

A picture taller than your cap, or faster than 60 frames a second, ends the stream with input_unsupported; an encoder that sends sound but no picture within 15 seconds of connecting ends it with input_no_video (an encoder that reconnects starts its picture at its next keyframe, so keep the keyframe interval at 1 to 2 seconds); an encoder that keeps sending above the bitrate cap for 30 seconds ends it with input_bitrate_exceeded. Watch what plycdn receives in stream.health (inputKbps, fps, keyframeSeconds, audio, width, height) on GET /live-inputs/{id} or GET /streams/{id}, and in the dashboard.

Going live from the browser

A web page can broadcast a camera, a microphone and a shared screen with nothing to install. The browser never holds a stream key: your server decides who may go live and gives that user a publish token.

browser ──► your server (is this user allowed to go live on this input?) ──► plycdn: publish token
browser ◄── token ────────────────────────────────────────────────────────┘
browser ── token ──► plycdn (WHIP address): the stream starts

A publish token is for one input, valid for the lifetime you ask for (1 second to 1 hour; 15 minutes if you do not say) and usable to start one stream. It is withdrawn if you replace the key, disable the input or delete it. From your server (admin key):

POST /api/content/v1/live-inputs/{id}/publish-tokens          # 201
{ "ttlSeconds": 900 }
{ "token": "lpt1.…", "expiresAt": "2026-10-04T10:15:00+00:00", "whipUrl": "https://whip-in-mum.live.plycdn.com/5f0e…/whip" }
PublishToken token = await videos.CreatePublishTokenAsync(orgId, liveInputId, TimeSpan.FromMinutes(15));
// token.Token and token.WhipUrl go to the browser; the token expires and starts one stream.

With the .NET controller you do not call this yourself: the browser calls POST api/plycdn/v1/live-inputs/{id}/publish-token on your backend, which asks your IPlycdnLiveAuthorizer whether the signed-in user may go live on that input and, if so, makes the token (Integration guide). Nobody may until you register one. The Angular and React packages' broadcaster (<plycdn-live-broadcaster>, <LiveBroadcaster>) does the rest: it asks for the token, opens the camera and microphone, shows a preview, a microphone level and the state in words, goes live, asks for a fresh token to reconnect when the connection drops, and ends with a sentence when the reconnect window is used up. Screen sharing is offered where the browser has it.

To publish from a page of your own, send the browser's WebRTC offer to whipUrl (WHIP) with the header Authorization: Bearer <token>; the answer is the WebRTC answer. Offer H.264 video and Opus audio. A refused token is publish_token_invalid.

Choosing a delivery mode

An input's delivery setting is how viewers receive its stream.

Broadcast (default) Real-time
Delay behind the camera about 2 to 4 seconds under 1 second
Audience size any size: it is delivered over our delivery network up to the safety cap (10,000 by default), then automatically broadcast for the rest
Qualities adaptive, up to the input's quality the viewer's connection steps between qualities
Recording and replay yes yes
Price stream minutes, plus delivery like any video stream minutes, plus a price per viewer-minute

Choose broadcast when the audience watches rather than answers: a conference keynote, a match, a worship service, a company all-hands, a webinar for hundreds. Two to four seconds behind is a normal live experience and it carries a stadium-sized audience at the usual delivery price. Choose real-time when what viewers do must reach the stage while it still matters: a live auction or a flash sale where bids close on the clock, quiz and betting formats, a speaker taking questions, a two-way town hall, a product demo with a live chat. A real-time input is also packaged for broadcast, so viewers beyond the real-time cap, or on a network that cannot hold a real-time connection, are given the broadcast stream instead of an error, and the recording needs nothing extra.

You choose the mode per input and can change it between streams (PATCH). At playback a real-time input can also be watched in broadcast mode (mode: "broadcast"); asking for real-time on a broadcast input answers broadcast links, because only a real-time input is served in real time (Watching).

Latency

Mode Typical delay What lowers or raises it
Real-time under 1 second A poor network makes the player step down in quality rather than fall behind
Broadcast, lowest 2 to 4 seconds Your encoder's own buffering adds to it; a keyframe every 1 to 2 seconds helps
Broadcast, balanced a few seconds further back Steadier for viewers on weak or mobile networks
Standard playback (a fallback) 6 to 10 seconds Used automatically for a viewer whose player or network cannot do low-latency playback; the stream's health.latency says standard

The delay you see also includes the encoder's own: set it to the lowest-delay profile it offers (in OBS, a 1 to 2 second keyframe interval and a fast encoder preset). The player lets a viewer pick Lowest delay or Smoother playback and shows a LIVE button that returns to the live edge after pausing or scrubbing back.

Watching a live stream

Viewers watch through links that your backend signs, as for any video. Ask for them with POST /sign and a liveInputId in place of a videoId (send the library as bucketId), with an optional mode (broadcast or realtime, the input's own when omitted) and ttlSeconds, and an ip only for a library that binds links to the viewer's address (below):

POST /api/content/v1/sign
{ "bucketId": "<libraryId>", "liveInputId": "<liveInputId>", "mode": "broadcast", "ttlSeconds": 900 }
{ "live": true, "mode": "broadcast", "latency": "low", "streamId": "…", "liveInputId": "…",
  "url": "https://acme-events.plycdn.net/v/<streamId>/ll/master.m3u8?token=…",
  "fallbackUrl": "https://acme-events.plycdn.net/v/<streamId>/master.m3u8?token=…",
  "expiresAt": "…" }

Give an ip only for a library that binds links to the viewer's address (ipBinding), and there it is required; on any other library an ip is refused with 422 validation_error. A live link without ip expires on the next five-minute boundary after ttlSeconds, so every viewer signed in the same five minutes gets the same link and even a very large audience is served from the edge. A link bound to a viewer's ip is theirs alone and expires exactly when asked.

  • Broadcast: url is the low-latency stream and fallbackUrl the standard one, for a player that cannot play low latency; latency is low or standard. Give url to your player; it plays like any stream and renews its links itself. For low latency use our players (<plycdn-live-player>, <LivePlayer>): for a player without our SDK, such as Safari's or AVPlayer's native one, use fallbackUrl (standard latency) as the safe default; low latency comes with our players.
  • Real-time: realtime is { "kind", "url", "token" }: kind is whep or rtc, and tells the player how to connect. For whep (the usual), url is the address and the token goes with it; whepUrl carries the same address with the token, for players that read the earlier field. For rtc, url is a wss:// address and the token is good for five minutes, enough to join: a player that needs to rejoin asks for new links. Our players handle both, and load what rtc needs only when it is used. The top-level url is the broadcast link for overflow. rungs names the qualities a viewer can choose, and latency describes the overflow link in url. Links last at most 24 hours. mode comes back broadcast instead of realtime when the input's own mode is broadcast, and when a real-time input's cap or capacity is reached: play what you are given. The first real-time viewer of a stream may see one automatic retry; nothing is needed from you. In broadcast rungs is null. Tags are refused on live links (422 tags_not_on_live) and so is hostname (422 hostname_not_on_live): custom domains are not available for live links.
  • While nothing is streaming the answer is 409 live_not_started with retryable: true. That is not a failure: try again in a few seconds (the players do, every 5 seconds, and show "Waiting for the stream to start").

Every live link answer also carries these, each described where it is explained:

Field What it is
captions [ { "language": "en", "url": "…" } ]: the address of each caption track, empty when the stream has none (live captions)
dvrWindowSeconds How far back a viewer may seek, in seconds; 0 when the input offers no rewind (rewinding)
realtime { "kind", "url", "token" } in real-time mode, null in broadcast
protection { "scheme", "keySystems" } when the stream is protected; absent otherwise (content protection)
watermark, logo What the player draws over the stream when the library or your brand shows them: a watermark of the fixed text and the date and time (mode show, no viewer details, no proof) and the player logo; absent otherwise (viewer watermark and player logo)
ads { "sessionId" } when the stream's ads are personalised: the viewer's own playback address is already in url, and a player needs nothing more. Absent when the stream is over its limit of personalised viewers (the answer is then the shared link), and absent when ads are off

The link of a recording (POST /sign with a videoId) carries protection too when the stream it came from was protected.

In ASP.NET Core, PlycdnVideoSigner.SignLiveAsync asks for these links, and POST api/plycdn/v1/sign with a liveInputId is the route your browser components call; your IPlycdnStorageAuthorizer decides it with PlycdnOperation.WatchVideo (the live input's id as key).

LivePlaybackLink link = await videoSigner.SignLiveAsync(orgId, libraryId, liveInputId, DeliveryMode.Broadcast);
// link.Url, link.FallbackUrl (broadcast) or link.WhepUrl (real-time), link.Mode, link.StreamId

In a page, use the packages' live player (<plycdn-live-player> in Angular, <LivePlayer> in React): it signs for you, chooses broadcast or real-time, stays close to live, steps down in quality for a weak connection, shows Waiting, Reconnecting and Ended in words (and More qualities coming while a stream that has just gone on air gets its other qualities), and when the stream ends plays the recording in the same place (Integration guide). Links last 15 minutes by default and the player renews them before they expire; a viewer can watch for hours.

Reconnecting and ending

When an encoder's connection drops, the stream waits for it for the input's reconnectWindowSeconds (default 60). Viewers see Reconnecting and playback picks up when the encoder returns, with a short jump where the picture was missing; the minutes in the gap are not billed. A stream is starting, live, reconnecting, ending, ended or failed (one that sent no picture within 30 seconds).

A stream ends when:

  • the window passes with no encoder (encoder_disconnected);
  • you end it: POST /live-inputs/{id}/end (ended_by_request; live_not_started, 409, when no stream is running);
  • it reaches maxDurationSeconds (max_duration_reached);
  • you disable the input (input_disabled), or plycdn suspends the account.

GET /live-inputs/{id}/streams lists an input's streams, newest first (cursor, limit 1 to 100, 50 by default), and GET /streams/{id} shows one: its state, endReason, delivery, quality, durationSeconds, startedAt, liveAt, endedAt, the protocol the encoder used, health, realtimeViewers, captions (while it has them) and recordingId. A stream that does not exist is video_not_found (404), because a stream is a video.

Backup ingest and redundant processing

For a broadcast that must not fail, send it twice. With backupIngest on, the input has a second set of publishing addresses on the same stream key, for a second encoder (or the same encoder over a second connection):

"ingest": { "rtmps": "…", "rtmp": "…", "srt": "…", "whip": "…",
            "rtmpsBackup": "rtmps://backup-in-mum.live.plycdn.com:443/5f0e…-backup?key={streamKey}",
            "rtmpBackup":  "rtmp://backup-in-mum.live.plycdn.com:1935/5f0e…-backup?key={streamKey}",
            "srtBackup":   "srt://backup-in-mum.live.plycdn.com:9000?streamid=publish:5f0e…-backup:live:{streamKey}&latency=120" }

The backup addresses are on their own host name, backup-{label}.live.plycdn.com (here backup-in-mum), served by separate machines so that losing one never takes both encoders; in a region without separate backup machines they are on the primary's host name. Either way, copy the addresses the input lists instead of building them, and allow both host names wherever your network limits where encoders may connect. The three backup addresses are present only while backupIngest is on. Each address takes one publisher at a time, so the primary and the backup can both be connected (a second encoder on an address already in use is refused with stream_key_in_use). The stream starts on whichever arrives first, and it can start on the backup alone.

If the encoder on the primary address stops sending for about two seconds, the stream switches to the backup without ending, and viewers see one short jump. It switches back to the primary only after the primary has been steady for about thirty seconds, so a flapping connection does not make the picture jump back and forth. Each switch sends the live.failover webhook (Live webhooks) and is counted in the stream's health history (viewers and health). The stream's reconnect window starts only when both are gone.

redundantTranscoding keeps a second copy of the processing of each stream ready. If the machine making your stream's qualities is lost, the standby carries on at once instead of the stream waiting to be rebuilt. It needs nothing from your encoder, and the two settings work together or apart.

Both are included wherever live streaming is in your plan; an account can have one left out, and then turning it on answers 409 live_setting_not_in_plan, detail.setting backupIngest or redundantTranscoding; an input that already had one on keeps it. Neither can be changed while a stream is running (409 live_input_busy). In the dashboard they are the stream's Settings → Resilience (Backup ingest, Redundant processing), which says whether your plan includes each before you save. Step by step: Backup ingest.

Share a live stream

A share link is an address anyone can open to watch a live input, with no account, no sign-in and nothing for you to sign. Send it in an email or a chat, or put it on a page. Viewers see Starting soon until the stream is on air, then the stream, then, when it ends, This stream has ended and the recording if you want it shown. Any number of people can watch through one link, and one input can have several links (up to 50), for example one per audience, each with its own password and expiry.

Create a link. In the dashboard, open the live input and choose Share links, then Create link. From your backend (an admin key):

ShareLink link = await videos.CreateShareLinkAsync(orgId, input.Id, new CreateShareLinkRequest(
    Label: "Town hall, all staff", Password: "meeting-2026", ExpiresAt: DateTimeOffset.UtcNow.AddDays(7), ShowRecording: true));
// link.Url is the address to give to viewers. The password is never shown again.

Every setting is optional:

  • Label: your own name for the link (1 to 100 characters), to tell links apart. Viewers never see it.
  • Password (4 to 128 characters): viewers must enter it before they can watch. After 5 wrong tries from one viewer in 15 minutes the link refuses that viewer for a while and says how many minutes to wait. Share the password separately from the link. It is stored in a form that cannot be read back, so hasPassword is all you can see; to change it, set a new one.
  • Expiry (ExpiresAt, a time in the future): from then on the link answers "This link is not available".
  • Show the recording (ShowRecording, on by default): when the stream ends, the link plays the recording as soon as it is ready. Turn it off to let the link end with the stream.

Change, turn off or remove a link. In the dashboard, use the link's row. From your backend:

await videos.UpdateShareLinkAsync(orgId, input.Id, link.Id, new UpdateShareLinkRequest { Disabled = true });    // off; Disabled = false turns it back on
await videos.UpdateShareLinkAsync(orgId, input.Id, link.Id, new UpdateShareLinkRequest { ClearPassword = true, ClearExpiresAt = true });
IReadOnlyList<ShareLink> links = await videos.ListShareLinksAsync(orgId, input.Id);                             // newest first
await videos.DeleteShareLinkAsync(orgId, input.Id, link.Id);                                                     // gone for good

A field you leave out is unchanged; the Clear… flags remove the label, the password or the expiry. A link that is turned off, expired or deleted answers "This link is not available" at once. A viewer already watching with the watch page sees it say so within a few seconds, and the picture stops.

What viewers see. Opening the address shows a page with the stream's title. The password box appears first when there is a password ("Wrong password, try again" for a wrong one). While the stream has not started the page says Starting soon and looks again every 10 seconds, so a viewer can open the link early and leave the tab open. A live stream plays a few seconds behind the encoder (broadcast delivery, whatever the input's delivery mode is) with a Live button and captions when the stream has them. When the stream ends the page says This stream has ended, then plays the recording if the link shows it and the recording is ready (a few minutes after the stream), or keeps the message. Playback links are renewed in the background, so a long stream is not interrupted.

On your own site. Instead of sending viewers to the address, put the stream on your own page with the watch component. It needs no sign-in and no route on your backend: it talks to plycdn directly. Give it the link's address (or just the code at its end):

<!-- Angular, from @plycdn/angular/video (add PlycdnVideoModule to your module) -->
<plycdn-watch code="https://watch.plycdn.com/AbCdEfGhIjKlMnOpQrStUv"></plycdn-watch>
// React, from @plycdn/react/video (no provider needed)
<PlycdnWatch code="https://watch.plycdn.com/AbCdEfGhIjKlMnOpQrStUv" />

Both take an optional apiBase (the plycdn API address, https://api.plycdn.com by default) and an options object that rewords every sentence and recolours the page. See SDK: Angular and SDK: React. The watch routes any page can call are in the API reference. If your site sends a Content-Security-Policy, add the API and the delivery hosts: connect-src https://api.plycdn.com https://*.plycdn.net, and img-src https://*.plycdn.net https://watch.plycdn.com for the page's images and your logo.

Brand your watch page

The page a share link opens can carry your look: your logo, your colours, your words and a button back to your site. Set it once for the organization and every link uses it; a link can then change the title, description, sentences or layout for itself. In the dashboard, open Account & security → Branding → Watch page: the preview beside the settings is the page viewers see. Step by step: Your watch page. From your backend (an admin key):

await videos.UpdateWatchBrandAsync(orgId, new UpdateWatchBrandRequest
{
    AccentColor = "#c2410c", BackgroundColor = "#101820", Layout = WatchLayouts.SidePanel, Title = "Acme Summit", Description = "Keynote and Q&A",
    Messages = new WatchMessages(Starting: "Doors open soon", Ended: "Thanks for joining"),
    SiteUrl = "https://acme.example/", SiteLabel = "Visit Acme", LogoSize = WatchLogoSizes.Large,
    FooterLinks = new[] { new WatchFooterLink("Privacy", "https://acme.example/privacy") },
});
await videos.UploadWatchBrandLogoAsync(orgId, File.OpenRead("logo.png"), "image/png");
  • Logo: PNG, JPEG or WebP, up to 512 KB. SVG and GIF are not accepted. It shows at the top of the page.
  • Logo size: small (the default: at most 32 pixels high), medium (48) or large (72; 56 on a phone). The logo keeps its proportions and never grows wider than the header. In the dashboard it is the Logo size choice in the Logo card, and the preview changes as you pick. Every link of the organization uses it.
  • Colours: #rrggbb. The accent colours buttons and the live mark; the background is the page. Leave the background out and pick a theme, dark (the default) or light. Text, buttons and lines are worked out so that they stay readable on whatever you choose.
  • Layout: standard (the picture with the title, description and links below it), side_panel (the picture with a panel beside it that holds the title, description, site button and links) or cinema (the picture edge to edge, with the title and site button over it while the page is active).
  • Title and description: the title defaults to the live input's name; the description (up to 2,000 characters) is optional.
  • Sentences: what the page says while the stream has not started, when it is over, and above the password box (up to 300 characters each). Defaults: "Starting soon", "This stream has ended", "Enter the password to watch". The sentences about a wrong password or too many tries are always plycdn's.
  • Site button and footer links: a button (label up to 40 characters, your site's name by default) and up to three footer links. Addresses must start with https://.

Everything is plain text: a title like Q&A <b>live</b> is shown exactly as typed. A field you leave out keeps its value; Clear… flags (ClearTitle, ClearAccentColor, ClearFooterLinks, and so on) return a field to its built-in value. A sub-organization shows its account's brand until it saves its own; its first change starts from the built-in look. GetWatchBrandAsync reads the brand (Inherited says whose it is) and DeleteWatchBrandLogoAsync removes the logo.

Per link. CreateShareLinkRequest and UpdateShareLinkRequest take Title, Description, Messages and Layout: for that link they win over the brand, field by field. Clear one to follow the brand again. The page a viewer sees uses the link's own value, then the brand's, then the built-in one. The watch component on your own site shows the same brand (Angular, React); what you set in its options wins over the brand.

Logo and watermark on the page. The page also draws your player logo and a watermark of your fixed text and the date and time over the stream, as the brand's playerLogo and watermark (or the library's own) say, in their positions and look. It names no viewer and is not required: a share link is a public link (Viewer watermark and player logo).

Use your own domain for watch pages

Instead of watch.plycdn.com, viewers can open share links on a hostname of yours, such as live.example.com/AbCdEfGhIjKlMnOpQrStUv, with a certificate for it. You can add up to five. A link then has one address for each active domain (ShareLink.Urls; Url stays on plycdn's host); every one of them opens the same link, with the same password, expiry and brand.

Use a subdomain. A watch domain is a name under your domain, such as www.example.com or live.example.com. A bare domain (example.com itself, or example.co.in) is refused with watch_domain_apex_unsupported: use a subdomain such as www.example.com or live.example.com, and redirect example.com to it at your DNS provider. The dashboard tells you as you type.

  1. Add the hostname. In the dashboard under Live streaming → Watch page → Watch domains (Add domain), or:

    WatchDomain domain = await videos.AddWatchDomainAsync(orgId, "live.example.com");
    foreach (WatchDomainRecord record in domain.Records)
        Console.WriteLine(quot;{record.Type} {record.Name} {record.Value}   ({record.Purpose})");
    
  2. Create the two DNS records at your DNS host, exactly as the answer (and the dashboard) lists them. Both are CNAME records to plycdn names:

    Type Name Value What it is for
    CNAME live.example.com watch-target.plycdn.net Points your domain to your watch pages
    CNAME _acme-challenge.live.example.com <your domain's own name>.dcv.plycdn.net Lets us issue and renew your certificate

    The second value is your domain's own; copy it from the answer. It also shows plycdn that the hostname is yours, so keep both records for as long as you use the domain: the certificate is renewed through the second one. Leave them unproxied at your DNS host (DNS only).

  3. Wait, or check now. plycdn looks for your records by itself. Each record in records has a status: found, missing, elsewhere (it points somewhere else) or unknown (not checked yet). To look at once, press Check now in the dashboard or call CheckWatchDomainAsync (at most once a minute per domain). The domain's state moves through:

    State What is happening
    pending_dns Waiting for both records to be visible. Usually minutes after you create them; after 72 hours without them it becomes failed (dns_not_configured).
    verifying Records found; plycdn is connecting the hostname. Minutes.
    issuing_certificate The hostname's certificate is being issued, usually within minutes. After 24 hours without one it becomes failed (certificate_failed).
    active Share links open on your hostname over HTTPS.
    failed, detached Stopped; failureReason says why (below). Check it again once the records are right, and it starts over.

    verification.checks shows the same look in more detail: ownership (the certificate record), routing (the record to your watch pages), claim (whether another account holds the hostname) and certificate.

Failure reasons. dns_not_configured: a record is missing or wrong; hostname_in_use: another account serves the hostname; certificate_failed: make sure both records are in place and nothing proxies the hostname; dns_record_removed and ownership_record_removed: a record you created was taken away, and the domain stops serving until it is back; provider_unavailable: plycdn could not finish just now, and tries again. Fix the record and check the domain again. GetWatchDomainAsync reads one domain, ListWatchDomainsAsync lists them, and RemoveWatchDomainAsync removes one (share links stop opening on it; delete its DNS records too).

Domains added before 7 October 2026 keep the records they were set up with (a TXT record at _plycdn.<your hostname> and the CNAME) and keep working; there is nothing to change. One that was still waiting for its records now lists the two CNAME records above instead.

A hostname can belong to one use at a time: one that serves a bucket as a custom domain cannot also be a watch domain, and plycdn's own names are refused (hostname_not_allowed). Adding a domain counts against the same hourly and daily allowances as custom domains for buckets.

Live captions

Turn on captions and each stream gets captions made from its speech while it is on air:

PATCH /api/content/v1/live-inputs/{id}
{ "settings": { "captions": { "enabled": true, "languages": ["en", "hi"], "mode": "realtime" } } }
  • languages is one or two language codes (for example en, es, hi), each one the library's region and residency offer; one it does not offer is 422 validation_error (fields naming languages). Captions on need at least one language. A change replaces the whole captions object, and applies from the next stream (409 live_input_busy while one runs).
  • mode is realtime (the default): captions appear a few seconds after the words are spoken. nearLive makes captions in short chunks, so they trail the picture by about half a minute. Plycdn serves nearLive where realtime was asked when real-time captions are not available (today captions are made near live) or live speech cannot be kept up; the mode in force is in the stream's captions.
  • English and the 22 scheduled languages of India are offered: en English, as Assamese, bn Bengali, brx Bodo, doi Dogri, gu Gujarati, hi Hindi, kn Kannada, ks Kashmiri, kok Konkani, mai Maithili, ml Malayalam, mni Manipuri, mr Marathi, ne Nepali, or Odia, pa Punjabi, sa Sanskrit, sat Santali, sd Sindhi, ta Tamil, te Telugu and ur Urdu. The speech is processed in India. A library with strict residency does not offer captions.
  • Captions come with a plan that includes them (live_captions). Without it, turning captions on answers 409 live_setting_not_in_plan with detail.setting captions. Step by step: Live captions. They are counted by the minute and by language (live_caption_minutes, Plans and prices).

A running stream carries its captions in stream.captions ({ "languages": ["en", "hi"], "mode": "realtime" }, null without captions). GET /streams/{id}/captions answers what a captions menu needs, with a standard key too:

{ "streamId": "a91c…", "mode": "realtime", "languages": [ { "language": "en", "name": "English" }, { "language": "hi", "name": "Hindi" } ] }

Without captions it answers "mode": null and "languages": []. The playback links for the stream carry captions, one entry per language with the address of its caption track (Watching); the players list them in their captions menu. A recording keeps the captions of its stream: they are the video's captions (language, label and the key of a .vtt file for each language).

Captions on a protected stream are made, but they are not encrypted: anyone with the stream's link can read them (content protection).

Rewinding a live stream

By default a viewer can seek back only a short way. Set dvrWindowSeconds (0 to 7,200, which is two hours; 0 by default, so a stream offers no rewind unless you ask) and viewers can seek back that far in the stream while it is on air. A DVR window is promised to the viewers of a running stream, so it changes only between streams (409 live_input_busy). The playback links say the window in force as dvrWindowSeconds, and the players' seek bar covers exactly that. Your safety cap live_dvr_seconds can hold the window lower: a window above the cap is refused (409 live_cap_reached, detail.cap live_dvr_seconds), and a cap set below an input's saved window shortens what it offers.

A DVR window cannot be combined with ads (settings that cannot be combined). The recording is the whole stream whatever the window.

Recordings

When a stream ends and the input has recording on, the stream's own video (recordingId, the same id as the stream) becomes playable and then ready like any uploaded video, with the usual video.playable and video.ready webhooks, at the same playback address, so a link to the live stream is a link to the replay. Nothing is encoded a second time and encoding is not charged; the recording is stored like any video (storage in the library's region, at the storage price). A video made by a stream carries liveInputId and, while it is on air, live: true, and the library lists it like any other.

A recording keeps the stream's captions (live captions), can be made searchable (searchable recordings), and stays protected when its stream was (content protection).

With recording off, the stream's files are removed an hour after it ends and live.ended carries no recording. Deleting the video while it is on air ends the stream. A stream that never went live (it ended before any picture was delivered, for example with input_no_video) leaves no video in the library and live.ended carries no recording; the stream stays in the input's history with its end reason.

Searchable recordings

The simplest way is the library's own switch (Make a video library searchable): every recording of the library is made searchable when it finishes. indexRecording on a single input still works, and a recording is never made searchable twice when both are on. Either way:

  • Your plan must include video and Content Search, or turning indexRecording on answers 409 live_setting_not_in_plan with detail.setting indexRecording.
  • The recording must have its download file, so downloads must be on in the library's processing settings; one without it shows Skipped: keep the original or the MP4 download to make videos searchable.
  • A library with strict residency cannot index recordings (409 live_setting_not_in_plan, indexRecording; with the library's switch, Skipped: residency).
  • A library that binds links to a viewer's address (ipBinding) does not (Skipped: protected delivery).
  • The recording of a protected stream is never indexed (never made searchable).
  • When captions were on for the stream, in one language, from its start to its end, the recording is made searchable from its captions: it is ready soon after the recording is, its passages are timed to the caption line, and speakers are not told apart. Otherwise it is transcribed as any recording. Either way it is charged as any recording, and for a recording finished since Content Search 1.17.0 the timing of its transcript is exact even where the stream had a gap (a reconnect): a result plays at the right moment. Recordings finished earlier keep their timing.
  • A recording identical to a file already indexed in your account is not transcribed again when we recognise it, which for a recording means reading it in full; one read in byte ranges, or one whose stream had a gap (timed to its own recording), is transcribed itself. See Duplicate content.
  • Turning an input's indexRecording off does not take recordings already made searchable out of search; Remove from search on the library does.
  • A recording that fails to be made searchable is withdrawn from search rather than left failed, and the recording itself stays a normal, playable video.

The recording itself is unaffected; a recording that is not searchable is still a normal, playable video.

Viewers and health

Two reads, with an admin key, describe a stream while it runs and after it ends (they are also the Viewers and Health screens of the dashboard).

GET /api/content/v1/streams/{id}/viewers?from=…&to=…&step=300
{ "streamId": "a91c…", "from": "…", "to": "…", "step": 300, "peakConcurrent": 812, "viewerMinutes": 20431.0,
  "broadcastCounted": true,
  "countries": [ { "country": "IN", "viewerMinutes": 9120 }, { "country": "US", "viewerMinutes": 4017 } ],
  "series": [ { "at": "…", "viewers": 790, "broadcast": 640, "realtime": 150, "viewerMinutes": 3950.0 } ] }

viewers is the most people watching in any one minute of the step, in both delivery modes together; broadcast and realtime split it. peakConcurrent is the same over the whole range and viewerMinutes is the watch time. countries lists the top ten countries by viewer-minutes, from broadcast viewers (real-time viewers are not placed in a country). from and to default to the stream's own span; step is 60, 300, 900 or 3,600 seconds (when left out, the smallest that gives about 500 points). A step that is not one of those, or a range of more than 1,500 points, is 422 validation_error. Viewers are counted, never identified: nothing about a viewer is stored but a count per minute and a country.

Broadcast viewers are counted from your library's delivery analytics. When the library has them off, broadcastCounted is false and only real-time viewers appear, so switch delivery analytics on for the library to count a broadcast audience.

GET /api/content/v1/streams/{id}/health?from=…&to=…&step=300
{ "streamId": "a91c…", "from": "…", "to": "…", "step": 300,
  "series": [ { "at": "…", "inputKbps": 4180.5, "fps": 29.97, "keyframeSeconds": 1.0, "speed": 1.01, "partPushP95Ms": 140, "gaps": 0, "failovers": 0 } ],
  "totals": { "gaps": 0, "failovers": 0 } }

A point carries what plycdn measured in that step: the incoming bitrate and frame rate, the keyframe interval, how fast the stream is being processed (speed, about 1 is keeping up), how long the slower parts of the stream took to be handed to delivery (partPushP95Ms, in milliseconds), and the number of gaps (a break in the incoming picture) and failovers (a backup takeover). A value is null when nothing reported it in that step. The history is kept 30 days. Both reads take the same from, to and step; an unknown stream is 404 video_not_found.

On a stream with ads, GET /streams/{id} carries health.ads: lastError (ad_server_unreachable while your ad server cannot be reached, otherwise null), breaks (how many were run), noFill (breaks where the ad server had no ad, so the slate was shown) and tracking (sent, failed and dropped: the impression and progress reports sent on to the ad server's tracking addresses).

A library with ipBinding accepts a link only from the IPv4 address it was signed for. That suits a desktop on a fixed network, and it suits mobile viewers badly: a phone moves between Wi-Fi and mobile data, and many mobile and home networks are IPv6 only, which IP-bound delivery cannot serve. A link signed for one address stops working the moment the viewer's address changes. For live, leave IP binding off, or accept that those viewers are refused until their player renews the link: your sign route must pass the viewer's current IPv4 address in ip every time it is asked (the .NET controller does, from the request's remote address, and refuses a viewer with no IPv4 address with 422 validation_error; the player asks again before each expiry and after a refusal), and use short links (ttlSeconds 300 to 900).

Restreaming to other platforms

A live input can send its stream on to other platforms at the same time (a social platform, a partner's site, another service): add each as a destination. Restreaming comes with a plan that includes it (live_restream); until it is switched on for your service every destination route answers 404 feature_not_available, and a plan without it answers 403 feature_not_in_plan. The routes need an admin key.

POST /api/content/v1/live-inputs/{id}/destinations            # 201
Idempotency-Key: <your own unique value>
{ "name": "Partner site", "url": "rtmps://live.partner.example/app", "key": "abcd-1234-efgh" }

Like every create, it needs an Idempotency-Key (400 idempotency_key_required without one): a retry with the same key and body answers the same destination, so a timeout never adds it twice. The .NET package sends a fresh key unless you pass your own.

{ "id": "d3f1…", "liveInputId": "5f0e…", "name": "Partner site", "url": "rtmps://live.partner.example/app",
  "state": "idle", "lastError": null, "startedAt": null, "createdAt": "…", "updatedAt": "…" }
  • url is the platform's address, rtmp:// or rtmps://, on port 443 or 1935, without the key in it; key is the stream key the platform issued you (1 to 512 printable characters). Never put the key in the address. An address that is anything else, carries a key or credentials, or whose name resolves to anything but a public address is 400 destination_url_invalid (the answer never says why). Plycdn's own addresses are refused too.
  • The key is never returned, in any answer, log or audit entry: it is accepted on create and change, held sealed, and removed the moment you delete the destination.
  • GET /live-inputs/{id}/destinations lists an input's destinations, oldest first ({ "items": [ … ] }). PATCH /destinations/{id} changes name, url or key (what you leave out is kept); a new address or key starts the destination over, and a push that is running reconnects with it within seconds. DELETE /destinations/{id} answers 204 and a push to it stops. Deleting the input deletes its destinations. An unknown destination is 404 destination_not_found.
  • At most 10 destinations per input unless your cap is raised (live_destinations): past it, 409 destination_limit_reached with detail.cap and detail.limit.
  • POST /destinations/{id}/test checks that the platform's address answers (the connection handshake only: nothing is published and the key is not used) and answers { "reachable": true }, or 502 destination_unreachable (retryable). A test takes a few seconds either way. Creating or changing an address, and testing, are limited per hour (429 rate_limited, retryable, with Retry-After), and one test runs at a time for your account.

While a stream is on air, each destination is pushed to automatically. Its state is idle (nothing is being sent), connecting, live or failed; lastError says why it last failed and is one of:

lastError Meaning
destination_unreachable The platform could not be reached, or stopped answering
destination_refused The platform did not accept the connection
destination_rejected_stream The platform refused the stream, usually a wrong or expired key, or a stream it is not ready for
destination_dropped The platform ended the connection
destination_address_forbidden The address now resolves to somewhere that is not allowed

Plycdn keeps trying. After three failures within five minutes the destination shows failed and the live.destination_failed webhook is sent once for that episode (Live webhooks). A stream that is protected is never restreamed. Restreaming is counted by the minute for each destination while it was pushing (restream_minutes, shown as Restreaming on your statement, Plans and prices).

Ad breaks and ads

An ad break is a stretch of a stream reserved for ads. You mark one from your backend (admin key) and the stream's playlists mark it for players. With ad insertion on, viewers see the ads of the break, or your slate (a short video you supply) where there is no ad. Ad insertion comes with a plan that includes it (live_ads; step by step: Ad breaks); until it is switched on for your service, ad settings and breaks answer 404 feature_not_available, and a plan without it answers 403 feature_not_in_plan.

Settings. On the input, ads:

"ads": { "enabled": true, "vmapUrl": "https://ads.example.com/vmap?break=[PODID]", "slate": "https://cdn.example.com/slate.mp4", "personalised": false }
  • vmapUrl (a VMAP 1.0 address) or vastUrl (a VAST 4.x tag), not both; ads that are enabled need one of them. Wrapper chains are followed up to five levels. slate is optional. Addresses are https:// on the default port, at most 2,048 characters, without credentials; the name must resolve to a public address. Anything else is 422 validation_error.
  • The whole ads object is replaced when you send it. Changes apply from the next break. "enabled": false switches ads off and leaves the rest saved.
  • Ads cannot be combined with content protection or with a DVR window on the same input: 409 live_setting_conflict (settings that cannot be combined).

Macros. In your address, plycdn fills in [CACHEBUSTING] (a random number), [TIMESTAMP], [BREAKMAXDURATION] (the break's length in seconds), [PODID] (the break's podId), and, for personalised ads only, [SESSIONID] and [CLIENTUA]. A macro it has no value for is sent as -1.

Shared and personalised. Without personalised, one decision is made for each break and every viewer sees it; its impressions and progress reports are sent on once per break, however many people watch, so count your audience with the players' own ad events (below). With personalised, each viewer's ads are asked for separately and reported once for that viewer. A personalised request carries the break's length, its podId, a timestamp, a random number and a pseudonym of the viewer's playback session ([SESSIONID]); your own address also receives the viewer's browser identification (the User-Agent, [CLIENTUA]), and ad servers your answer passes the request to receive the same without it. No viewer's address or cookie is ever sent. Personalised ads are served to a limited number of viewers at once for each stream (2,000 unless raised); a viewer beyond it sees the shared ads, and the playback link plycdn gives that viewer has no ads (Watching).

Marking a break.

POST /api/content/v1/live-inputs/{id}/breaks                  # 201
{ "durationSeconds": 30, "at": "now", "podId": "midroll-1" }

durationSeconds is more than 0 and at most 600; at is "now" (the default) or a time with its offset within the next 24 hours (a time up to ten seconds ago counts as now); podId is up to 64 letters, digits and _ . : -. The break starts on the nearest segment boundary. The answer:

{ "id": "b71a…", "liveInputId": "5f0e…", "streamId": "a91c…", "state": "scheduled", "durationSeconds": 30,
  "requestedAt": "…", "startedAt": null, "endedAt": null, "podId": "midroll-1" }

state is scheduled, started, ended, missed (the stream was not being prepared when the break was due) or cancelled. 409 live_not_started (retryable) when the input has no stream on air; 409 live_input_busy when the break would overlap one already asked for; 409 live_cap_reached with detail.cap scheduled_breaks (16 waiting at once); a time in the past or more than a day ahead is 422 validation_error. The live.ad_break webhook is sent when a break starts. Health for ads is in viewers and health.

Listing and cancelling breaks.

GET    /api/content/v1/live-inputs/{id}/breaks?limit=20                 # {"items": [Break]}, newest first
DELETE /api/content/v1/live-inputs/{id}/breaks/{breakId}                # 200: the Break, now "cancelled"

The list holds the input's planned and recent breaks (limit 1 to 100, 50 when left out). A cancelled break keeps its row with "state": "cancelled" and cancelledAt. Only a scheduled break more than 45 seconds away can be cancelled: one that started, ended, was missed or cancelled, or is due within 45 seconds (it is already being prepared) answers 409 ad_break_not_cancellable, with its detail.state; a break that isn't on this input answers 404 ad_break_not_found. Both need an admin key. In the dashboard, the stream's Overview → Ad breaks inserts, plans, lists and cancels them. ListAdBreaksAsync and CancelAdBreakAsync, listAdBreaks and cancelAdBreak, list_ad_breaks and cancel_ad_break do it from your code; cancelling is recorded in the audit log as live.break_cancelled.

Content protection

Protection encrypts a stream and its recording so only players that obtain a key can play it. It is available through a protection setup configured for your account: your own key service, set up with us (contact us); plycdn does not run a key service of its own. GET /live/protection-setups (admin key) lists the setups your account may name, as {"items": [{"name": "standard"}]} (empty without one); in the dashboard they are the choices of the stream's Settings → Protection → Content protection. Step by step: Content protection.

PATCH /api/content/v1/live-inputs/{id}
{ "settings": { "protection": { "provider": "<the name we give you>", "options": { } } } }

provider is the name of the setup available to your account and options its settings (a plain list of names and values, at most 16). They are settings, not secrets: a credential is never written in an option, and the setup tells you how to reference one. "provider": "none" switches protection off. A name that is not available to your account, or options it refuses, is 400 protection_not_configured where you save it, and the same code (409) refuses a stream start rather than ever starting one in the clear. Protection applies from the next stream.

When a stream, or its recording, is protected, its playback link carries protection:

"protection": { "scheme": "cbcs",
                "keySystems": [ { "system": "fairplay", "licenseUrl": "https://…", "certificateUrl": "https://…" },
                                { "system": "widevine", "licenseUrl": "https://…" },
                                { "system": "playready", "licenseUrl": "https://…" } ] }

system is widevine, playready, fairplay or clearkey (each at most once); licenseUrl is where the player asks for a key and certificateUrl (FairPlay) where it fetches the certificate; both are https://. The addresses can be bound to the viewer: they expire with the link and carry the same address binding. Our players pick the first system the browser supports; with your own player, do the same. When the setup cannot give the key information the link is refused with 503 protection_not_configured (retryable): no link is ever given for a protected stream without it.

What protection changes:

  • A protected stream is never offered in real time: the link answers mode: "broadcast", with realtime and whepUrl null.
  • A protected stream has no ads and is not restreamed.
  • Captions on a protected stream are made, but are not encrypted.
  • A protected recording stays protected. It has no poster, no thumbnails and no download, and it is not searchable: indexRecording skips it.
  • Sign a protected recording through plycdn (POST /sign with its videoId; in .NET SignVideoFromPlycdnAsync): only that answer carries its protection, and a link signed in your own process has none.
  • The live player plays a protected stream while it is live. When the stream ends it hands the recording to the video player (<plycdn-player>, PlycdnPlayer), which does not play protected video in this release: for a protected stream, turn the live player's playRecording off and play the protected recording in a player of your own that uses protection the way the live player does.

Settings that cannot be combined

On together Answer
ads (enabled) and protection 409 live_setting_conflict, detail.settings ["ads", "protection"]: an ad is clear media and cannot be placed in encrypted content
ads (enabled) and dvrWindowSeconds above 0 409 live_setting_conflict, detail.settings ["ads", "dvrWindowSeconds"]: inserted ads cannot be kept consistent with a rewind window yet, so a stream with ads cannot offer rewind

The conflict is refused when you save either setting while the other is on, in either order, and again when a stream starts (an input saved with both some other way): nothing starts. Ads that are switched off ("enabled": false) can sit beside either.

Live webhooks

Seven events tell your backend how a broadcast is going; subscribe an endpoint to any of them as for video events, and verify them the same way. Each carries the ids in data, not a video:

Event Sent when data
live.connected An encoder or browser connected and was accepted; viewers cannot watch yet. Sent again, with reconnected: true, when it returns inside the window liveInputId, streamId, protocol
live.started The first picture is out: viewers can watch. Once per stream liveInputId, streamId, delivery, quality
live.disconnected The encoder dropped; the stream waits for it liveInputId, streamId, reconnectWindowSeconds
live.ended The stream ended liveInputId, streamId, endReason, durationSeconds, recording ({ "id": "…" }, or null when the input does not record)
live.failover With backup ingest: the stream switched from one publisher to the other. Once per switch liveInputId, streamId, from, to (each primary or backup)
live.destination_failed A restream destination failed three times within five minutes. Once per episode; never carries the address or key liveInputId, streamId, destinationId, name, error (a lastError value)
live.ad_break An ad break started liveInputId, streamId, breakId, durationSeconds, startedAt
{"id":"…","type":"live.ended","createdAt":"…","organizationId":"…","data":{"liveInputId":"5f0e…","streamId":"a91c…","endReason":"ended_by_request","durationSeconds":3612,"recording":{"id":"a91c…"}}}

Use live.failover to tell your crew a backup took over, and live.destination_failed to tell whoever watches the partner platform to check the key. Use live.started to show "we are live" on your site and live.ended to publish the replay once video.ready follows. In .NET, PlycdnWebhookEvent.AsLive() reads them and PlycdnWebhookVerifier.LiveStarted, LiveEnded and the others name them. Events can arrive more than once and out of order: act once per Plycdn-Delivery, and read state from the API when order matters.

Safety caps

Each organization has safety limits on live streaming. They protect you from a runaway encoder and are not a sales limit; plycdn raises any of them on request, and the new value applies to the next request:

Cap Default Reached when
live_concurrent_streams 25 A stream is started while that many are running
live_stream_max_seconds 86,400 (24 hours) A setting asks for a longer maxDurationSeconds
live_max_height 1,080 A setting asks for a taller top quality, or an encoder sends a taller picture (input_unsupported)
live_max_kbps 12,000 An encoder sends above it for 30 seconds (input_bitrate_exceeded)
live_realtime_viewers_per_stream 10,000 More real-time viewers arrive: the rest are given broadcast
live_inputs 1,000 A new input would exceed it
live_dvr_seconds none (7,200 at most) A setting asks for a dvrWindowSeconds above it
live_destinations 10 A new restream destination would exceed it on that input (destination_limit_reached)
scheduled_breaks 16 More than 16 ad breaks wait on one stream (a fixed limit; detail.cap says so)

Reaching the limit on simultaneous streams, on inputs, or a usage allowance never cuts a stream that is running: it refuses the next one, with live_cap_reached (409; detail.cap names the cap and detail.limit its value) or live_quota_exceeded (409, when a usage allowance set on your account is used up). A picture taller than its cap or a bitrate above its cap for 30 seconds does end the running stream (input_unsupported, input_bitrate_exceeded), and so does a stream that runs longer than its longest allowed time (max_duration_reached). To raise a cap, ask your plycdn contact and say which one.

The caps in force for your organization are in GET /api/content/v1/plan, in limits under the names above (all but scheduled_breaks), while live streaming is in your plan; a cap that does not apply is left out. The dashboard shows them under Billing & usage → Usage → Plan → Live streaming limits, and the server packages read one by name (ContentPlan.Limit(PlanLimits.LiveConcurrentStreams), planLimit(plan, PLAN_LIMITS.LiveConcurrentStreams), plan_limit(plan, "live_concurrent_streams")).

Live errors

Code Status What to do
live_input_not_found 404 Unknown or deleted live input, or another organization's
live_not_started 409 Asking for playback links (or to end) while the input has no stream. Retryable: try again in a few seconds
live_realtime_unavailable 503 A real-time link could not be made just now. Retryable: ask again in a few seconds, or ask for mode: "broadcast"
live_input_disabled 409 The input is disabled: enable it, or use another
live_input_busy 409 Deleting an input, or changing a setting that is fixed while a stream runs (backupIngest, redundantTranscoding, captions, dvrWindowSeconds), while a stream runs: end it first or wait. Also an ad break that overlaps one already asked for
live_cap_reached 409 A safety cap is reached; detail.cap says which. A running stream is not affected
tags_not_on_live 422 tags sent with a live playback link: leave them out
hostname_not_on_live 422 hostname sent with a live playback link: custom domains are not available for live links
live_quota_exceeded 409 The live allowance set on your account is used up
ad_break_not_cancellable 409 Cancelling an ad break that has started, ended, was missed or cancelled, or is due within 45 seconds; detail.state says its state
ad_break_not_found 404 No such ad break on this live input
publish_token_invalid 401 An encoder's key or a browser's token was refused: wrong, replaced, expired, already used for a stream, or the input was disabled. Get a new token (browser) or check the key (encoder)
stream_key_in_use 409 Another encoder is already publishing to this input
feature_not_available 404 Live streaming is not switched on for your service yet; the same for destinations (restreaming) and ad breaks while those are not switched on
feature_not_in_plan 403 Your plan does not include live streaming, restreaming or ad insertion
region_not_available 400 Creating an input in a library whose region does not offer live streaming
live_setting_not_in_plan 409 A setting your plan or service does not include was turned on; detail.setting names it (backupIngest, redundantTranscoding, captions, indexRecording)
live_setting_conflict 409 Two settings cannot be on together: detail.settings is ["ads", "protection"] or ["ads", "dvrWindowSeconds"] (settings that cannot be combined). Also refuses a stream start
protection_not_configured 400, 409, 503 The protection setup is not available to your account or refused its options: 400 where you save it, 409 when a stream would start, 503 (retryable) on a playback link
destination_url_invalid 400 A restream address is not an rtmp:// or rtmps:// address on port 443 or 1935, carries a key or credentials, or does not resolve to a public address
destination_not_found 404 Unknown or deleted destination, or another organization's
destination_limit_reached 409 The input already has as many destinations as its live_destinations cap allows; detail.cap and detail.limit say
destination_unreachable 502 A destination test could not reach the platform. Retryable; it is also a destination's lastError (restreaming)
rate_limited 429 Too many wrong keys or tokens from one address, or too many destination creates, address changes or tests; wait for Retry-After
share_link_not_found 404 Unknown or deleted share link, or another input's
share_link_limit_reached 409 The input already has 50 share links (detail.limit): delete one you no longer use
watch_link_not_found 404 On the public watch routes: the address is not a share link, or it is turned off, expired or deleted, or the stream cannot be watched any more
watch_not_started 409 On the public watch routes: the stream has not started. Retryable: the watch component looks again every 10 seconds
watch_ended 409 On the public watch routes: the stream is over and there is no recording to show
watch_password_required 401 On the public watch routes: the link has a password and none, or a wrong one, was sent
watch_password_attempts 429 On the public watch routes: too many wrong passwords; wait for Retry-After (also detail.retryAfter, in seconds)
logo_invalid 422 The watch page logo is not a PNG, JPEG or WebP, or its type does not match the file (SVG and GIF are not accepted)
logo_too_large 413 The watch page logo is over 512 KB
watch_domain_limit_reached 409 You already have five watch domains (detail.limit): remove one
watch_domain_not_found 404 Unknown or removed watch domain, or another organization's
domain_exists 409 You already added this hostname
hostname_not_allowed 422 A hostname that cannot be used: plycdn's own names, or one that is not a public name

An encoder using RTMP or SRT is simply disconnected when it is refused; a WHIP request is answered with the code.

A stream ends with one of these reasons (endReason of the stream and of live.ended):

endReason Meaning
encoder_disconnected The encoder did not return within the reconnect window
ended_by_request You ended it with POST /live-inputs/{id}/end
max_duration_reached It ran as long as maxDurationSeconds
input_disabled The input was disabled (or the account suspended)
input_unsupported The picture was taller than your cap allows (1,080 lines by default) or faster than 60 frames a second (fixed), or quality source was chosen for a picture that is not H.264
input_no_video No picture arrived within 15 seconds of connecting: the encoder sent sound only, or its keyframe interval is longer than that. Add a video source and set a keyframe every 1 to 2 seconds
input_bitrate_exceeded The encoder kept sending above live_max_kbps
processing_failed plycdn could not process the stream: no picture arrived within 30 seconds, or processing failed. Start again; contact us if it repeats

11Webhooks

A webhook tells your backend when a video changes, so you never have to poll: mark a lesson available when its video is playable or ready, alert someone when one failed.

Creating an endpoint. Your endpoint must be https:// and publicly reachable:

POST /api/content/v1/webhooks
{ "url": "https://api.customer.example/plycdn", "events": ["video.ready", "video.failed"], "description": "LMS" }

The answer (201) includes a secret (pwhs_…). It is shown once: store it with your other secrets now; plycdn keeps it only in sealed form and never shows it again. An organization can have up to 10 endpoints (webhook_limit_reached), each subscribed to any of the events below. Each sub-organization has its own endpoints and hears only about its own videos. PATCH /webhooks/{webhookId} changes url, events, description (null removes it) and active (false stops deliveries without deleting the endpoint); DELETE /webhooks/{webhookId} deletes it. An address that is not https:// is validation_error; one that is not printable ASCII (use the xn-- form of an international name), not on port 443, carries credentials, or resolves to a private, local or otherwise non-public address is webhook_url_invalid. A paused endpoint (active: false) is sent nothing: a delivery due while it is paused ends failed with no lastError, and redelivering one answers it unchanged until you resume the endpoint.

Event Sent when
video.playable The video's lowest quality is ready and it plays
video.ready Every quality is ready
video.failed The video failed; data.video.errorCode says why
live.connected, live.started, live.disconnected, live.ended, live.failover, live.destination_failed, live.ad_break A live stream's progress and its backup, restream and ad events; their data carries the ids, not a video (Live webhooks)
signing_profile.changed A bucket's or library's signing key, domains, link settings, serial playback or watermark requirement changed. The server packages use it to refresh their cached signing settings; data is bucketId (the bucket or library), kind (bucket or library) and reasons (any of key_rotated, domains_changed, delivery_changed, serial_changed, scheme_changed, watermark_changed) (When the signing settings change)
webhook.ping Only when you ping the endpoint (below); never subscribed to

Each video event is sent once per video, when the video enters that status.

The request. A POST to your URL with a compact JSON body:

{"id":"8b9c…","type":"video.ready","createdAt":"2026-09-26T10:15:00+00:00","organizationId":"…","data":{"video":{"id":"…","libraryId":"…","title":"Week 1: Introduction","status":"ready","errorCode":null,"…":"…"}}}

data.video is the Video shape (Statuses), as it was at that moment. The headers:

Header Value
Content-Type application/json
User-Agent plycdn-webhooks/1
Plycdn-Event The event, as in type
Plycdn-Delivery This delivery's id: the same on every retry of it
Plycdn-Webhook The endpoint's id
Plycdn-Signature t=<unix seconds>,v1=<hex signature>, with a second v1 during a secret rotation

Verifying the signature. Always verify before acting on a webhook: anyone can send a request to your URL. In ASP.NET Core, PlycdnWebhookVerifier.ReadAsync reads the body, verifies it and parses it:

app.MapPost("/plycdn", async (HttpRequest request, IOptions<MyPlycdnSecrets> secrets, Lessons lessons) =>
{
    PlycdnWebhookEvent evt;
    try { evt = await PlycdnWebhookVerifier.ReadAsync(request, secrets.Value.WebhookSecrets); }
    catch (PlycdnWebhookSignatureException) { return Results.Unauthorized(); }

    if (!await lessons.FirstTimeAsync(request.Headers["Plycdn-Delivery"].ToString()))
        return Results.Ok();                                   // already handled: a retry of a delivery we took

    if (evt.Type == "video.ready" && evt.AsVideo() is { } video)
        await lessons.PublishAsync(video.Id);
    return Results.Ok();
});

PlycdnWebhookVerifier.Verify(body, signatureHeader, secrets) does the same over bytes you already hold. In words: take t and each v1 from Plycdn-Signature; compute HMAC-SHA256 with the secret as the key over the bytes of t, a ., then the exact body bytes as received (not re-serialized JSON); the request is genuine when that, in lower-case hex, equals any v1 (compare in constant time) and t is within 5 minutes of your clock. In Node:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyPlycdn(body: Buffer, header: string | undefined, secrets: string[], toleranceSeconds = 300): boolean {
  const parts = (header ?? '').split(',').map(p => p.trim().split('=', 2));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  const given = parts.filter(([k, v]) => k === 'v1' && /^[0-9a-f]{64}$/.test(v ?? '')).map(([, v]) => Buffer.from(v, 'hex'));
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds || !given.length) return false;
  return secrets.some(secret => {
    const expected = createHmac('sha256', secret).update(`${t}.`).update(body).digest();
    return given.some(v => timingSafeEqual(v, expected));
  });
}

(Read the body raw, for example express.raw({ type: 'application/json' }), before any JSON parser touches it.)

Answer quickly, and expect repeats. Answer any 2xx within 10 seconds, then do the work afterwards (a queue, a background job); a slower answer is a failed attempt. A delivery can arrive more than once (your answer was lost, or you asked for a redelivery), so deduplicate by Plycdn-Delivery as above. Events can arrive out of order: rely on data.video.status, not on the order of arrival.

Retries. A delivery that is not answered with a 2xx is tried again after 1 minute, 5 minutes, 15 minutes, 30 minutes, 1, 2, 4, 8 and 12 hours, then 24 hours twice: 12 attempts over about three days, after which it is failed. Answering 410 Gone stops retrying that delivery at once (it is failed). Redirects are never followed. An endpoint is never switched off because its deliveries fail: fix it, then redeliver what it missed.

Rotating the secret. POST /webhooks/{webhookId}/secret/rotate answers a new secret (shown once) and previousSecretExpiresAt. For the next 24 hours every delivery carries two signatures, one with each secret, so you can deploy the new secret without missing anything; configure both on your side during the change (ReadAsync accepts any of the secrets you give it). After 24 hours only the new secret signs.

Ping. POST /webhooks/{webhookId}/ping sends a real, signed webhook.ping to the endpoint ("data": { "webhookId": "…" }), whatever it is subscribed to: use it to check your verification end to end. It answers the delivery (202), which you can follow in the log.

Limit. Pings, redeliveries and secret rotations together are limited to 60 an hour for your account (across its organizations; refused calls count). Past that they answer 429 rate_limited with Retry-After in seconds, and nothing is sent or changed.

The delivery log. GET /webhooks/{webhookId}/deliveries lists deliveries, newest first (state = pending, succeeded or failed; cursor; limit 1 to 200, default 50), each with its attempts, the last answer's status and time, and the payload that was sent. The log keeps the last 90 days: a finished delivery (succeeded or failed) is removed 90 days after it was created, so redeliver or record what you need before then. The dashboard shows the same under Developers → Webhooks. POST /webhook-deliveries/{deliveryId}/redeliver sends a finished delivery once more, with the same Plycdn-Delivery and body (a delivery still pending is already on its way, and is left as it is; so is one whose endpoint is paused).

A failed attempt's lastError says what happened:

lastError What happened What to do
timeout No answer within 10 seconds Answer first, then do the work
connection_failed The connection was refused or dropped Check that the endpoint is up and reachable from the internet
tls_failed The TLS handshake failed Serve a valid certificate for the endpoint's name, from a public certificate authority
dns_failed The name did not resolve Check the URL and your DNS
address_forbidden The name resolved to a private, local or otherwise non-public address Publish the endpoint on a public address
redirect_not_followed The endpoint answered with a redirect (lastStatus says which) Use the final URL as the endpoint
http_error The endpoint answered, but not with a 2xx (lastStatus has the status) Check your endpoint's logs for that time
var hook = await plycdn.CreateWebhookAsync(organizationId,
    new CreateWebhookRequest(new Uri("https://api.customer.example/plycdn"), new[] { "video.ready", "video.failed" }, "LMS"));
await secrets.SaveAsync("plycdn-webhook", hook.Secret);        // shown once
await plycdn.PingWebhookAsync(organizationId, hook.Id);
var failed = await plycdn.ListWebhookDeliveriesAsync(organizationId, hook.Id, state: "failed");
foreach (var delivery in failed.Items)
    await plycdn.RedeliverWebhookAsync(organizationId, delivery.Id);
// Express, with verifyPlycdn from above
app.post('/plycdn', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifyPlycdn(req.body, req.get('Plycdn-Signature'), [process.env.PLYCDN_WEBHOOK_SECRET!])) return res.sendStatus(401);
  res.sendStatus(204);                                         // answer first
  const event = JSON.parse(req.body.toString('utf8'));
  if (await firstTime(req.get('Plycdn-Delivery')!)) await queue.add(event);
});

12Errors

Code Status What to do
library_not_found 404 Unknown library id, a files bucket's id, or another organization's library
video_not_found 404 Unknown video id, a deleted video, another organization's, or (on /sign) a video from another library or one taken down
video_not_ready 409 /sign for a video that is not playable or ready yet. Wait for the video.playable webhook, or check status
domain_not_active 409 /sign or /playback-sessions named a hostname that is not the library's own hostname or one of its active custom domains: add the domain to this library and wait until it is active
serial_playback_requires_session 409 This library's videos play only through a playback session: POST /playback-sessions (the server packages' sign route does it for you)
serial_playback_needs_plycdn_links 409 This library can't turn on serial playback yet: contact support to move it onto serial playback, or create a new library with serial playback on
serial_playback_unavailable 409 A live stream's recording can't be played in a library with serial playback
serial_playback_busy 409 The library is being moved to another delivery network, so serial playback can't be turned on yet. Retryable: wait for Retry-After and send it again
progress_not_found 404 The viewer (resumeId) hasn't started this video, or was started over since and hasn't watched it again
playback_session_expired 410 A progress save for a session that has ended, or for a pass that isn't one plycdn gave, or a watermark renewal more than 120 seconds after the session ended: start a new session (the players do)
watermark_required 409 The library requires the viewer watermark: play it through a playback session with watermark, from a player that draws it (Viewer watermark and player logo)
watermark_proof_invalid 403 A renewal whose proof doesn't belong to the session or viewer (details or resumeId), or a session renewed twice. The player stops, unless it answers the retry of a renewal that got no answer: then it starts one fresh session
watermark_tampered 403 The player reported the watermark removed or hidden. The player stops
bucket_suspended 403 plycdn has taken the library down: no new videos and no playback links until it is reinstated (Takedowns)
not_included_in_plan 403 Video is not part of your plan
video_source_exists 409 A video was already made from this key (an upload under sources/, from any tool). The key stays listed in sources/ through the S3 and Azure endpoints, and deleting it there is refused too. Delete that video first, or upload under another name
plan_limit_reached 403 Your plan's bucket limit is reached; libraries count towards it
original_not_kept 409 Encoding a video again, when its library did not keep the original. Videos made while keepOriginal was false cannot be encoded again
validation_error 422 fields names what is wrong: for example [["body","key"]] for a library upload outside sources/, [["body","processing","ladder",0]] for a quality that does not exist, [["body","visibility"]] for a library made public, [["body","url"]] for a webhook address that is not https://
webhook_not_found 404 Unknown or deleted endpoint, or another organization's
webhook_delivery_not_found 404 Unknown delivery, or another organization's
webhook_url_invalid 400 The endpoint's URL is not printable ASCII, not on port 443, carries credentials, or resolves to a private, local or otherwise non-public address. Publish it on a public address
webhook_limit_reached 409 You have 10 endpoints already. Delete one, or subscribe one endpoint to more events
forbidden 403 Your IPlycdnStorageAuthorizer refused the browser's request (GetVideo or WatchVideo)
playback_unsupported — Shown by the player, never answered by plycdn: this browser can play the stream in neither form. Suggest a current browser
playback_link_failed — Shown by the player: three renewals in a row failed or were refused, or the stream's address could not be reached. Check that your backend's sign route answers and the viewer's connection, then Try again

The live codes (live_input_not_found, live_not_started and the rest) are under Live errors. A video's errorCode values are under Statuses and a webhook delivery's lastError values under Webhooks. Everything else (bucket_not_found, bucket_not_active, upload codes) is as in the Storage guide, Errors.

try { return Ok(await signer.SignVideoAsync(organizationId, libraryId, videoId)); }
catch (PlycdnException e) when (e.Code is "video_not_ready") { return Conflict(new { code = e.Code }); }
const { error } = usePlayback(libraryId, videoId);
if (error?.code === 'video_not_ready') return <p>This video is still being prepared.</p>;