Skip to content
rachel/workerd
File

Blob: types/defines/stream.d.ts

typescript785 lines
1/**
2 * Binding entrypoint for Cloudflare Stream.
3 *
4 * Usage:
5 * - Binding-level operations:
6 *   `await env.STREAM.videos.upload`
7 *   `await env.STREAM.videos.createDirectUpload`
8 *   `await env.STREAM.videos.*`
9 *   `await env.STREAM.watermarks.*`
10 * - Per-video operations:
11 *   `await env.STREAM.video(id).downloads.*`
12 *   `await env.STREAM.video(id).captions.*`
13 *
14 * Example usage:
15 * ```ts
16 * await env.STREAM.video(id).downloads.generate();
17 *
18 * const video = env.STREAM.video(id)
19 * const captions = video.captions.list();
20 * const videoDetails = video.details()
21 * ```
22 */
23interface StreamBinding {
24  /**
25   * Returns a handle scoped to a single video for per-video operations.
26   * @param id The unique identifier for the video.
27   * @returns A handle for per-video operations.
28   */
29  video(id: string): StreamVideoHandle;
30  /**
31   * Uploads a new video from a provided URL.
32   * @param url The URL to upload from.
33   * @param params Optional upload parameters.
34   * @returns The uploaded video details.
35   * @throws {BadRequestError} if the upload parameter is invalid or the URL is invalid
36   * @throws {QuotaReachedError} if the account storage capacity is exceeded
37   * @throws {MaxFileSizeError} if the file size is too large
38   * @throws {RateLimitedError} if the server received too many requests
39   * @throws {AlreadyUploadedError} if a video was already uploaded to this URL
40   * @throws {InternalError} if an unexpected error occurs
41   */
42  upload(url: string, params?: StreamUrlUploadParams): Promise<StreamVideo>;
43  /**
44   * Creates a direct upload that allows video uploads without an API key.
45   * @param params Parameters for the direct upload
46   * @returns The direct upload details.
47   * @throws {BadRequestError} if the parameters are invalid
48   * @throws {RateLimitedError} if the server received too many requests
49   * @throws {InternalError} if an unexpected error occurs
50   */
51  createDirectUpload(
52    params: StreamDirectUploadCreateParams
53  ): Promise<StreamDirectUpload>;
54 
55  videos: StreamVideos;
56  watermarks: StreamWatermarks;
57}
58 
59/**
60 * Handle for operations scoped to a single Stream video.
61 */
62interface StreamVideoHandle {
63  /**
64   * The unique identifier for the video.
65   */
66  id: string;
67  /**
68   * Get a full videos details
69   * @returns The full video details.
70   * @throws {NotFoundError} if the video is not found
71   * @throws {InternalError} if an unexpected error occurs
72   */
73  details(): Promise<StreamVideo>;
74  /**
75   * Update details for a single video.
76   * @param params The fields to update for the video.
77   * @returns The updated video details.
78   * @throws {NotFoundError} if the video is not found
79   * @throws {BadRequestError} if the parameters are invalid
80   * @throws {InternalError} if an unexpected error occurs
81   */
82  update(params: StreamUpdateVideoParams): Promise<StreamVideo>;
83  /**
84   * Deletes a video and its copies from Cloudflare Stream.
85   * @returns A promise that resolves when deletion completes.
86   * @throws {NotFoundError} if the video is not found
87   * @throws {InternalError} if an unexpected error occurs
88   */
89  delete(): Promise<void>;
90  /**
91   * Creates a signed URL token for a video.
92   * @returns The signed token that was created.
93   * @throws {InternalError} if the signing key cannot be retrieved or the token cannot be signed
94   */
95  generateToken(): Promise<string>;
96 
97  downloads: StreamScopedDownloads;
98  captions: StreamScopedCaptions;
99}
100 
101interface StreamVideo {
102  /**
103   * The unique identifier for the video.
104   */
105  id: string;
106  /**
107   * A user-defined identifier for the media creator.
108   */
109  creator: string | null;
110  /**
111   * The thumbnail URL for the video.
112   */
113  thumbnail: string;
114  /**
115   * The thumbnail timestamp percentage.
116   */
117  thumbnailTimestampPct: number;
118  /**
119   * Indicates whether the video is ready to stream.
120   */
121  readyToStream: boolean;
122  /**
123   * The date and time the video became ready to stream.
124   */
125  readyToStreamAt: string | null;
126  /**
127   * Processing status information.
128   */
129  status: StreamVideoStatus;
130  /**
131   * A user modifiable key-value store.
132   */
133  meta: Record<string, string>;
134  /**
135   * The date and time the video was created.
136   */
137  created: string;
138  /**
139   * The date and time the video was last modified.
140   */
141  modified: string;
142  /**
143   * The date and time at which the video will be deleted.
144   */
145  scheduledDeletion: string | null;
146  /**
147   * The size of the video in bytes.
148   */
149  size: number;
150  /**
151   * The preview URL for the video.
152   */
153  preview?: string;
154  /**
155   * Origins allowed to display the video.
156   */
157  allowedOrigins: Array<string>;
158  /**
159   * Indicates whether signed URLs are required.
160   */
161  requireSignedURLs: boolean | null;
162  /**
163   * The date and time the video was uploaded.
164   */
165  uploaded: string | null;
166  /**
167   * The date and time when the upload URL expires.
168   */
169  uploadExpiry: string | null;
170  /**
171   * The maximum size in bytes for direct uploads.
172   */
173  maxSizeBytes: number | null;
174  /**
175   * The maximum duration in seconds for direct uploads.
176   */
177  maxDurationSeconds: number | null;
178  /**
179   * The video duration in seconds. -1 indicates unknown.
180   */
181  duration: number;
182  /**
183   * Input metadata for the original upload.
184   */
185  input: StreamVideoInput;
186  /**
187   * Playback URLs for the video.
188   */
189  hlsPlaybackUrl: string;
190  dashPlaybackUrl: string;
191  /**
192   * The watermark applied to the video, if any.
193   */
194  watermark: StreamWatermark | null;
195  /**
196   * The live input id associated with the video, if any.
197   */
198  liveInputId?: string | null;
199  /**
200   * The source video id if this is a clip.
201   */
202  clippedFromId: string | null;
203  /**
204   * Public details associated with the video.
205   */
206  publicDetails: StreamPublicDetails | null;
207}
208 
209type StreamVideoStatus = {
210  /**
211   * The current processing state.
212   */
213  state: string;
214  /**
215   * The current processing step.
216   */
217  step?: string;
218  /**
219   * The percent complete as a string.
220   */
221  pctComplete?: string;
222  /**
223   * An error reason code, if applicable.
224   */
225  errorReasonCode: string;
226  /**
227   * An error reason text, if applicable.
228   */
229  errorReasonText: string;
230};
231 
232type StreamVideoInput = {
233  /**
234   * The input width in pixels.
235   */
236  width: number;
237  /**
238   * The input height in pixels.
239   */
240  height: number;
241};
242 
243type StreamPublicDetails = {
244  /**
245   * The public title for the video.
246   */
247  title: string | null;
248  /**
249   * The public share link.
250   */
251  share_link: string | null;
252  /**
253   * The public channel link.
254   */
255  channel_link: string | null;
256  /**
257   * The public logo URL.
258   */
259  logo: string | null;
260};
261 
262type StreamDirectUpload = {
263  /**
264   * The URL an unauthenticated upload can use for a single multipart request.
265   */
266  uploadURL: string;
267  /**
268   * A Cloudflare-generated unique identifier for a media item.
269   */
270  id: string;
271  /**
272   * The watermark profile applied to the upload.
273   */
274  watermark: StreamWatermark | null;
275  /**
276   * The scheduled deletion time, if any.
277   */
278  scheduledDeletion: string | null;
279};
280 
281type StreamDirectUploadCreateParams = {
282  /**
283   * The maximum duration in seconds for a video upload.
284   */
285  maxDurationSeconds: number;
286  /**
287   * The date and time after upload when videos will not be accepted.
288   */
289  expiry?: string;
290  /**
291   * A user-defined identifier for the media creator.
292   */
293  creator?: string;
294  /**
295   * A user modifiable key-value store used to reference other systems of record for
296   * managing videos.
297   */
298  meta?: Record<string, string>;
299  /**
300   * Lists the origins allowed to display the video.
301   */
302  allowedOrigins?: Array<string>;
303  /**
304   * Indicates whether the video can be accessed using the id. When set to `true`,
305   * a signed token must be generated with a signing key to view the video.
306   */
307  requireSignedURLs?: boolean;
308  /**
309   * The thumbnail timestamp percentage.
310   */
311  thumbnailTimestampPct?: number;
312  /**
313   * The date and time at which the video will be deleted. Include `null` to remove
314   * a scheduled deletion.
315   */
316  scheduledDeletion?: string | null;
317  /**
318   * The watermark profile to apply.
319   */
320  watermark?: StreamDirectUploadWatermark;
321};
322 
323type StreamDirectUploadWatermark = {
324  /**
325   * The unique identifier for the watermark profile.
326   */
327  id: string;
328};
329 
330type StreamUrlUploadParams = {
331  /**
332   * Lists the origins allowed to display the video. Enter allowed origin
333   * domains in an array and use `*` for wildcard subdomains. Empty arrays allow the
334   * video to be viewed on any origin.
335   */
336  allowedOrigins?: Array<string>;
337  /**
338   * A user-defined identifier for the media creator.
339   */
340  creator?: string;
341  /**
342   * A user modifiable key-value store used to reference other systems of
343   * record for managing videos.
344   */
345  meta?: Record<string, string>;
346  /**
347   * Indicates whether the video can be a accessed using the id. When
348   * set to `true`, a signed token must be generated with a signing key to view the
349   * video.
350   */
351  requireSignedURLs?: boolean;
352  /**
353   * Indicates the date and time at which the video will be deleted. Omit
354   * the field to indicate no change, or include with a `null` value to remove an
355   * existing scheduled deletion. If specified, must be at least 30 days from upload
356   * time.
357   */
358  scheduledDeletion?: string | null;
359  /**
360   * The timestamp for a thumbnail image calculated as a percentage value
361   * of the video's duration. To convert from a second-wise timestamp to a
362   * percentage, divide the desired timestamp by the total duration of the video. If
363   * this value is not set, the default thumbnail image is taken from 0s of the
364   * video.
365   */
366  thumbnailTimestampPct?: number;
367  /**
368   * The identifier for the watermark profile
369   */
370  watermarkId?: string;
371};
372 
373interface StreamScopedCaptions {
374  /**
375   * Uploads the caption or subtitle file to the endpoint for a specific BCP47 language.
376   * One caption or subtitle file per language is allowed.
377   * @param language The BCP 47 language tag for the caption or subtitle.
378   * @param input The caption or subtitle stream to upload.
379   * @returns The created caption entry.
380   * @throws {NotFoundError} if the video is not found
381   * @throws {BadRequestError} if the language or file is invalid
382   * @throws {InternalError} if an unexpected error occurs
383   */
384  upload(language: string, input: ReadableStream): Promise<StreamCaption>;
385  /**
386   * Generate captions or subtitles for the provided language via AI.
387   * @param language The BCP 47 language tag to generate.
388   * @returns The generated caption entry.
389   * @throws {NotFoundError} if the video is not found
390   * @throws {BadRequestError} if the language is invalid
391   * @throws {StreamError} if a generated caption already exists
392   * @throws {StreamError} if the video duration is too long
393   * @throws {StreamError} if the video is missing audio
394   * @throws {StreamError} if the requested language is not supported
395   * @throws {InternalError} if an unexpected error occurs
396   */
397  generate(language: string): Promise<StreamCaption>;
398  /**
399   * Lists the captions or subtitles.
400   * Use the language parameter to filter by a specific language.
401   * @param language The optional BCP 47 language tag to filter by.
402   * @returns The list of captions or subtitles.
403   * @throws {NotFoundError} if the video or caption is not found
404   * @throws {InternalError} if an unexpected error occurs
405   */
406  list(language?: string): Promise<StreamCaption[]>;
407  /**
408   * Removes the captions or subtitles from a video.
409   * @param language The BCP 47 language tag to remove.
410   * @returns A promise that resolves when deletion completes.
411   * @throws {NotFoundError} if the video or caption is not found
412   * @throws {InternalError} if an unexpected error occurs
413   */
414  delete(language: string): Promise<void>;
415}
416 
417interface StreamScopedDownloads {
418  /**
419   * Generates a download for a video when a video is ready to view. Available
420   * types are `default` and `audio`. Defaults to `default` when omitted.
421   * @param downloadType The download type to create.
422   * @returns The current downloads for the video.
423   * @throws {NotFoundError} if the video is not found
424   * @throws {BadRequestError} if the download type is invalid
425   * @throws {StreamError} if the video duration is too long to generate a download
426   * @throws {StreamError} if the video is not ready to stream
427   * @throws {InternalError} if an unexpected error occurs
428   */
429  generate(
430    downloadType?: StreamDownloadType
431  ): Promise<StreamDownloadGetResponse>;
432  /**
433   * Lists the downloads created for a video.
434   * @returns The current downloads for the video.
435   * @throws {NotFoundError} if the video or downloads are not found
436   * @throws {InternalError} if an unexpected error occurs
437   */
438  get(): Promise<StreamDownloadGetResponse>;
439  /**
440   * Delete the downloads for a video. Available types are `default` and `audio`.
441   * Defaults to `default` when omitted.
442   * @param downloadType The download type to delete.
443   * @returns A promise that resolves when deletion completes.
444   * @throws {NotFoundError} if the video or downloads are not found
445   * @throws {InternalError} if an unexpected error occurs
446   */
447  delete(downloadType?: StreamDownloadType): Promise<void>;
448}
449 
450interface StreamVideos {
451  /**
452   * Lists all videos in a users account.
453   * @returns The list of videos.
454   * @throws {BadRequestError} if the parameters are invalid
455   * @throws {InternalError} if an unexpected error occurs
456   */
457  list(params?: StreamVideosListParams): Promise<StreamVideo[]>;
458}
459 
460interface StreamWatermarks {
461  /**
462   * Generate a new watermark profile
463   * @param input The image stream to upload
464   * @param params The watermark creation parameters.
465   * @returns The created watermark profile.
466   * @throws {BadRequestError} if the parameters are invalid
467   * @throws {InvalidURLError} if the URL is invalid
468   * @throws {TooManyWatermarksError} if the number of allowed watermarks is reached
469   * @throws {InternalError} if an unexpected error occurs
470   */
471  generate(
472    input: ReadableStream,
473    params: StreamWatermarkCreateParams
474  ): Promise<StreamWatermark>;
475  /**
476   * Generate a new watermark profile
477   * @param url The image url to upload
478   * @param params The watermark creation parameters.
479   * @returns The created watermark profile.
480   * @throws {BadRequestError} if the parameters are invalid
481   * @throws {InvalidURLError} if the URL is invalid
482   * @throws {TooManyWatermarksError} if the number of allowed watermarks is reached
483   * @throws {InternalError} if an unexpected error occurs
484   */
485  generate(
486    url: string,
487    params: StreamWatermarkCreateParams
488  ): Promise<StreamWatermark>;
489  /**
490   * Lists all watermark profiles for an account.
491   * @returns The list of watermark profiles.
492   * @throws {InternalError} if an unexpected error occurs
493   */
494  list(): Promise<StreamWatermark[]>;
495  /**
496   * Retrieves details for a single watermark profile.
497   * @param watermarkId The watermark profile identifier.
498   * @returns The watermark profile details.
499   * @throws {NotFoundError} if the watermark is not found
500   * @throws {InternalError} if an unexpected error occurs
501   */
502  get(watermarkId: string): Promise<StreamWatermark>;
503  /**
504   * Deletes a watermark profile.
505   * @param watermarkId The watermark profile identifier.
506   * @returns A promise that resolves when deletion completes.
507   * @throws {NotFoundError} if the watermark is not found
508   * @throws {InternalError} if an unexpected error occurs
509   */
510  delete(watermarkId: string): Promise<void>;
511}
512 
513type StreamUpdateVideoParams = {
514  /**
515   * Lists the origins allowed to display the video. Enter allowed origin
516   * domains in an array and use `*` for wildcard subdomains. Empty arrays allow the
517   * video to be viewed on any origin.
518   */
519  allowedOrigins?: Array<string>;
520  /**
521   * A user-defined identifier for the media creator.
522   */
523  creator?: string;
524  /**
525   * The maximum duration in seconds for a video upload. Can be set for a
526   * video that is not yet uploaded to limit its duration. Uploads that exceed the
527   * specified duration will fail during processing. A value of `-1` means the value
528   * is unknown.
529   */
530  maxDurationSeconds?: number;
531  /**
532   * A user modifiable key-value store used to reference other systems of
533   * record for managing videos.
534   */
535  meta?: Record<string, string>;
536  /**
537   * Indicates whether the video can be a accessed using the id. When
538   * set to `true`, a signed token must be generated with a signing key to view the
539   * video.
540   */
541  requireSignedURLs?: boolean;
542  /**
543   * Indicates the date and time at which the video will be deleted. Omit
544   * the field to indicate no change, or include with a `null` value to remove an
545   * existing scheduled deletion. If specified, must be at least 30 days from upload
546   * time.
547   */
548  scheduledDeletion?: string | null;
549  /**
550   * The timestamp for a thumbnail image calculated as a percentage value
551   * of the video's duration. To convert from a second-wise timestamp to a
552   * percentage, divide the desired timestamp by the total duration of the video. If
553   * this value is not set, the default thumbnail image is taken from 0s of the
554   * video.
555   */
556  thumbnailTimestampPct?: number;
557};
558 
559type StreamCaption = {
560  /**
561   * Whether the caption was generated via AI.
562   */
563  generated?: boolean;
564  /**
565   * The language label displayed in the native language to users.
566   */
567  label: string;
568  /**
569   * The language tag in BCP 47 format.
570   */
571  language: string;
572  /**
573   * The status of a generated caption.
574   */
575  status?: 'ready' | 'inprogress' | 'error';
576};
577 
578type StreamDownloadStatus = 'ready' | 'inprogress' | 'error';
579 
580type StreamDownloadType = 'default' | 'audio';
581 
582type StreamDownload = {
583  /**
584   * Indicates the progress as a percentage between 0 and 100.
585   */
586  percentComplete: number;
587  /**
588   * The status of a generated download.
589   */
590  status: StreamDownloadStatus;
591  /**
592   * The URL to access the generated download.
593   */
594  url?: string;
595};
596 
597/**
598 * An object with download type keys. Each key is optional and only present if that
599 * download type has been created.
600 */
601type StreamDownloadGetResponse = {
602  /**
603   * The audio-only download. Only present if this download type has been created.
604   */
605  audio?: StreamDownload;
606  /**
607   * The default video download. Only present if this download type has been created.
608   */
609  default?: StreamDownload;
610};
611 
612type StreamWatermarkPosition =
613  | 'upperRight'
614  | 'upperLeft'
615  | 'lowerLeft'
616  | 'lowerRight'
617  | 'center';
618 
619type StreamWatermark = {
620  /**
621   * The unique identifier for a watermark profile.
622   */
623  id: string;
624  /**
625   * The size of the image in bytes.
626   */
627  size: number;
628  /**
629   * The height of the image in pixels.
630   */
631  height: number;
632  /**
633   * The width of the image in pixels.
634   */
635  width: number;
636  /**
637   * The date and a time a watermark profile was created.
638   */
639  created: string;
640  /**
641   * The source URL for a downloaded image. If the watermark profile was created via
642   * direct upload, this field is null.
643   */
644  downloadedFrom: string | null;
645  /**
646   * A short description of the watermark profile.
647   */
648  name: string;
649  /**
650   * The translucency of the image. A value of `0.0` makes the image completely
651   * transparent, and `1.0` makes the image completely opaque. Note that if the image
652   * is already semi-transparent, setting this to `1.0` will not make the image
653   * completely opaque.
654   */
655  opacity: number;
656  /**
657   * The whitespace between the adjacent edges (determined by position) of the video
658   * and the image. `0.0` indicates no padding, and `1.0` indicates a fully padded
659   * video width or length, as determined by the algorithm.
660   */
661  padding: number;
662  /**
663   * The size of the image relative to the overall size of the video. This parameter
664   * will adapt to horizontal and vertical videos automatically. `0.0` indicates no
665   * scaling (use the size of the image as-is), and `1.0 `fills the entire video.
666   */
667  scale: number;
668  /**
669   * The location of the image. Valid positions are: `upperRight`, `upperLeft`,
670   * `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores the
671   * `padding` parameter.
672   */
673  position: StreamWatermarkPosition;
674};
675 
676type StreamWatermarkCreateParams = {
677  /**
678   * A short description of the watermark profile.
679   */
680  name?: string;
681  /**
682   * The translucency of the image. A value of `0.0` makes the image completely
683   * transparent, and `1.0` makes the image completely opaque. Note that if the
684   * image is already semi-transparent, setting this to `1.0` will not make the
685   * image completely opaque.
686   */
687  opacity?: number;
688  /**
689   * The whitespace between the adjacent edges (determined by position) of the
690   * video and the image. `0.0` indicates no padding, and `1.0` indicates a fully
691   * padded video width or length, as determined by the algorithm.
692   */
693  padding?: number;
694  /**
695   * The size of the image relative to the overall size of the video. This
696   * parameter will adapt to horizontal and vertical videos automatically. `0.0`
697   * indicates no scaling (use the size of the image as-is), and `1.0 `fills the
698   * entire video.
699   */
700  scale?: number;
701  /**
702   * The location of the image.
703   */
704  position?: StreamWatermarkPosition;
705};
706 
707type StreamVideosListParams = {
708  /**
709   * The maximum number of videos to return.
710   */
711  limit?: number;
712  /**
713   * Return videos created before this timestamp.
714   * (RFC3339/RFC3339Nano)
715   */
716  before?: string;
717  /**
718   * Comparison operator for the `before` field.
719   * @default 'lt'
720   */
721  beforeComp?: StreamPaginationComparison;
722  /**
723   * Return videos created after this timestamp.
724   * (RFC3339/RFC3339Nano)
725   */
726  after?: string;
727  /**
728   * Comparison operator for the `after` field.
729   * @default 'gte'
730   */
731  afterComp?: StreamPaginationComparison;
732};
733 
734type StreamPaginationComparison = 'eq' | 'gt' | 'gte' | 'lt' | 'lte';
735 
736/**
737 * Error object for Stream binding operations.
738 */
739interface StreamError extends Error {
740  readonly code: number;
741  readonly statusCode: number;
742  readonly message: string;
743  readonly stack?: string;
744}
745 
746interface InternalError extends StreamError {
747  name: 'InternalError';
748}
749 
750interface BadRequestError extends StreamError {
751  name: 'BadRequestError';
752}
753 
754interface NotFoundError extends StreamError {
755  name: 'NotFoundError';
756}
757 
758interface ForbiddenError extends StreamError {
759  name: 'ForbiddenError';
760}
761 
762interface RateLimitedError extends StreamError {
763  name: 'RateLimitedError';
764}
765 
766interface QuotaReachedError extends StreamError {
767  name: 'QuotaReachedError';
768}
769 
770interface MaxFileSizeError extends StreamError {
771  name: 'MaxFileSizeError';
772}
773 
774interface InvalidURLError extends StreamError {
775  name: 'InvalidURLError';
776}
777 
778interface AlreadyUploadedError extends StreamError {
779  name: 'AlreadyUploadedError';
780}
781 
782interface TooManyWatermarksError extends StreamError {
783  name: 'TooManyWatermarksError';
784}