@vidispine/vdt-js 23.4.0-pre.2 → 23.4.0-pre.4

package/dist/index.d.ts

@@ -4,6 +4,8 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import type { AudioComponentType } from '@vidispine/types';
 import type { BinaryComponentType } from '@vidispine/types';
 import type { CollectionType } from '@vidispine/types';
@@ -30,6 +32,271 @@ import type { VideoComponentType } from '@vidispine/types';
 
 declare type ArrayElement<ArrayType> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
 
+/**
+ * Representation of a chunk sent by `ChunkUpload`
+ *
+ * @category Upload
+ */
+export declare class Chunk {
+    state: ChunkState;
+    eventBus: ChunkedUploadEventBus;
+    tryTimeout: NodeJS.Timeout;
+    transferPromise: any;
+    start: number;
+    end: number;
+    fileSize: number;
+    blobSlice: any;
+    api: {
+        method?: (options: {
+            file: any;
+            onUploadProgress: (progressEvent: {
+                loaded: number;
+            }) => void;
+            headers?: {
+                index: number;
+                size: number;
+            };
+        }) => any;
+        props?: any;
+    };
+    constructor(props?: ChunkProps);
+    /**
+     * Attempt to transfer chunk with some fault resilience.
+     *
+     * - 3 retires with 1 second apart in case of failure
+     * - Pauses/resumes chunk transfer when network is offline/online
+     *
+     * @returns Promise of the transfer request
+     */
+    tryTransfer(): Promise<Chunk>;
+    /**
+     * Transfers `blobSlice` on this object with the `api.method`
+     *
+     * Triggers: `EVENTS.progress`
+     * Status: `STATUSES.transferring`
+     *
+     * @returns Promise for the transfer
+     */
+    transfer(): any;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+    get transferRate(): number;
+    private onComplete;
+}
+
+/**
+ * Class for sending and controlling multiple `ChunkedUpload` objects
+ *
+ * @category Upload
+ */
+export declare class ChunkedTransferManager {
+    initialState: ChunkedTransferManagerState;
+    state: ChunkedTransferManagerState;
+    options: ChunkedTransferManagerOptions;
+    events: ChunkedUploadEventBus;
+    constructor(options?: ChunkedTransferManagerOptions);
+    get transfers(): ChunkedUpload[];
+    get status(): number;
+    set status(value: number);
+    get bytesTotal(): number;
+    get bytesDone(): number;
+    get isUploading(): boolean;
+    get paused(): boolean;
+    bindNetworkEvents(): void;
+    addChunkedUpload(chunkedUpload: ChunkedUpload): void;
+    removeChunkedUpload(InstanceOrFileOrTransferId: ChunkedUpload | File | string, force?: boolean): void;
+    onProgress(): void;
+    onComplete(): void;
+    exists(file: File): ChunkedUpload;
+    isTransferAvailable(transfer: any): boolean;
+    pause(): Promise<any>;
+    resume(): void;
+    retry(): void;
+    upload(): void;
+    onFail(error: any, state: ChunkedUpload['state']): void;
+    reset(): void;
+    destroy(): void;
+    get hasCompleted(): boolean;
+    updateStats(): void;
+    get percentDone(): number;
+    get fileList(): any[];
+}
+
+export declare type ChunkedTransferManagerOptions = {
+    maxConcurrentFileTransfers: number;
+    autoResume: boolean;
+};
+
+export declare type ChunkedTransferManagerState = {
+    status: number;
+    transfers: ChunkedUpload[];
+    bytesDone: number;
+    bytesTotal: number;
+    lastStats: {
+        bytesDone: number;
+        bytesTotal: number;
+    };
+};
+
+/**
+ * Class for dividing blobs/files into chunks and sending them through the supplied `options.api.method`
+ *
+ * @category Upload
+ */
+export declare class ChunkedUpload {
+    readonly DEFAULT_OPTIONS: ChunkedUploadOptions;
+    eventBus: ChunkedUploadEventBus;
+    options: ChunkedUploadOptions;
+    state: ChunkedUploadState;
+    constructor(file: File, options: ChunkedUploadOptions);
+    upload(): void;
+    getByteRangesForChunks(blob: Blob, chunkSize?: number): any[];
+    addChunksFromBlob(blob: Blob): void;
+    retry(): void;
+    resume(): void;
+    pause(): Promise<Chunk[]>;
+    cancel(): Promise<Chunk[]>;
+    autoAdjustMaxConcurrentTransfers(stats: any): void;
+    onProgress(): void;
+    onComplete(): void;
+    getStats(): {
+        totalChunks: number;
+        completedChunks: number;
+        totalBytes: number;
+        transferredBytes: number;
+        avgTransferRate: number;
+        concurrentTransfers: number;
+    };
+    set concurrentTransfers(int: any);
+    set rate(int: number);
+    get rate(): number;
+    get finalResponse(): false | object;
+    get transferId(): string;
+}
+
+/**
+ * Event bus used by `Chunk`, `ChunkedUpload` and `ChunkedTransferManager` to communicate
+ *
+ * @category Upload
+ */
+export declare class ChunkedUploadEventBus {
+    events: ChunkedUploadEventBusEvents;
+    constructor();
+    /**
+     * Add a callback for a specific event type
+     *
+     * @param event event type
+     * @param callback function receiving state of chunk, transfer manager or chunked upload instance
+     */
+    on(event: EVENTS, callback: (data: Chunk['state'] | ChunkedTransferManager['state'] | ChunkedUpload['state'], error?: any) => void): void;
+    /**
+     * Remove all callbacks for a specific event type
+     *
+     * @param event event type
+     */
+    off(event: EVENTS): void;
+    /**
+     * Trigger callbacks for a specific event
+     *
+     * @param event
+     * @param data
+     * @returns
+     */
+    trigger(event: EVENTS, data: Chunk['state'] | ChunkedTransferManager['state'] | ChunkedUpload['state'], error?: any): void;
+}
+
+export declare type ChunkedUploadEventBusEvents = {
+    [key in EVENTS]?: Array<(data: Chunk['state'] | ChunkedTransferManager['state'] | ChunkedUpload['state'], error?: any) => void>;
+};
+
+export declare type ChunkedUploadOptions = {
+    targetRate?: number;
+    chunkSize?: number;
+    minChunkSize?: number;
+    maxConcurrentTransfers?: number;
+    maxConcurrentFileTransfers?: number;
+    autoMaxConcurrentTransfers?: boolean;
+    minFileSize?: number;
+    api?: {
+        props?: {
+            pathParams?: {
+                [key: string]: any;
+            };
+            queryParams?: {
+                transferId?: string;
+                [key: string]: any;
+            };
+            data?: any;
+        };
+        method?: any;
+        [key: string]: any;
+    };
+    /**
+     * ChunkedTransferManager -> automatically resume transfers when network connection become active
+     */
+    autoResume?: boolean;
+    onComplete?: (finalResponse?: false | object) => void;
+    onProgress?: (stats?: ChunkedUploadStats) => void;
+    onFail?: (error?: any) => void;
+};
+
+export declare type ChunkedUploadState = {
+    blob: {
+        name: string;
+        lastModified: number;
+        size: number;
+    };
+    chunks: Chunk[];
+    status: number;
+    transferPromises: Promise<Chunk>[];
+    targetRate: number;
+    rate: number;
+    autoMaxConcurrentTransfers: boolean;
+    maxConcurrentTransfers: number;
+    mime: string;
+    transferId: string;
+    lastStats: {};
+};
+
+export declare type ChunkedUploadStats = {
+    totalChunks?: number;
+    completedChunks?: number;
+    totalBytes?: number;
+    transferredBytes?: number;
+    avgTransferRate?: number;
+    concurrentTransfers?: number;
+};
+
+export declare type ChunkProps = {
+    start?: number;
+    end?: number;
+    fileSize?: number;
+    blobSlice?: any;
+    api?: {
+        method?: (options?: {
+            file?: any;
+            onUploadProgress?: (progressEvent: {
+                loaded: number;
+            }) => void;
+            headers?: {
+                index: number;
+                size: number;
+            };
+        }) => any;
+        props?: any;
+    };
+};
+
+export declare type ChunkState = {
+    retries: number;
+    status: number;
+    startTime: number | null;
+    completeTime: number | null;
+    response: any;
+    bytesTransferred: number | null;
+};
+
 /**
  * Create a VidiCore metadata object from a more dense/simplified structure
  *
@@ -83,8 +350,6 @@ export declare const createTimeCode: (timeCode: TimeCodeInput | string | number,
 
 export declare type CreateTimeCodeOptions = TimeCodeInputOptions | FormatTimeCodeSmpteOptions | FormatTimeCodeSecondsOptions | FormatTimeCodeTextOptions;
 
-export declare const defaultOptions: ParseSearchResultEventsOptions;
-
 /**
  * Const object with document types
  *
@@ -101,6 +366,27 @@ export declare const DOCUMENT_TYPES: {
 declare type DocumentType_2 = keyof typeof DOCUMENT_TYPES;
 export { DocumentType_2 as DocumentType }
 
+/**
+ * Chunked upload event types
+ *
+ * @category Upload
+ */
+export declare enum EVENTS {
+    progress = "progress",
+    update = "update",
+    complete = "complete",
+    error = "error",
+    added = "upload-added",
+    removed = "upload-removed",
+    failed = "upload-failed",
+    retry = "retry",
+    pausing = "pausing",
+    paused = "paused",
+    resuming = "resuming",
+    offline = "offline",
+    online = "online"
+}
+
 /**
  * Array with all available metadata field attributes
  *
@@ -156,8 +442,38 @@ export declare const FILE_STATES: {
     readonly AWAITING_SYNC: "AWAITING_SYNC";
 };
 
+export declare type FileLike = Partial<File> & {
+    path?: string;
+};
+
+/**
+ * Converts a list of files into a tree structure
+ *
+ * Works with `path` or the native `webkitRelativePath`
+ *
+ * @param files An array of file like objects
+ * @returns A file tree object
+ *
+ * @category Upload
+ */
+export declare const fileListToFileTree: (files: FileLike[]) => {
+    [key: string]: FileTree;
+};
+
 export declare type FileStateTypes = keyof typeof FILE_STATES;
 
+export declare type FileTree = {
+    file: File;
+    path?: string;
+    progress?: {
+        totalBytes: number;
+        transferredBytes: number;
+    };
+    files?: {
+        [fileName: string]: FileTree;
+    };
+};
+
 export declare type FilteredShapeListObject = {
     src: string;
     type: string;
@@ -253,6 +569,12 @@ export declare interface FormatTimeCodeSecondsOptions extends TimeCodeInputOptio
      * e.g. `1.04 => 104@100 => 26@25` (if no explicit `timeBase` is set)
      */
     useGCD?: boolean;
+    /**
+     * Select if it should floor, round or ceil if conforming seconds to the supplied timebase
+     *
+     * @default `'floor'`
+     */
+    roundingMode?: 'floor' | 'ceil' | 'round';
 }
 
 /**
@@ -303,6 +625,27 @@ export declare interface FormatTimeCodeTextOptions extends TimeCodeInputOptions
  */
 export declare const formatTimeCodeType: (timeCode: TimeCodeInput, options?: TimeCodeInputOptions) => TimeCode;
 
+/**
+ * Filter a shape type list to get shapes that are playable in a browser
+ *
+ * The mime types "video/quicktime" & "video/x-m4v" are considered "video/mp4" if:
+ * 1. container format is "MPEG-4" or "mov"
+ * 2. video codec is "h264"
+ *
+ * @param itemType
+ * @param options
+ * @returns
+ *
+ * @category Shape
+ */
+export declare const getPlayerSources: (itemType: ItemType, options?: GetPlayerSourcesOptions) => PlayerSource[];
+
+export declare type GetPlayerSourcesOptions = {
+    allowedMimeTypes?: string[];
+    allowedMethods?: string[];
+    streamingServers?: string[];
+};
+
 /**
  * Return a const for the document type of a shape (looks at mimeType)
  *
@@ -635,7 +978,7 @@ export declare type ParsedMetadataType<TOptions> = (TOptions extends {
     includeMetadataAttributes?: true | string[];
 } ? ParsedMetadataAttributes : {});
 
-export declare type ParsedSearchResultEntryTimespanType = {
+declare type ParsedSearchResultEntryTimespanType = {
     entityType?: 'Item' | 'Collection';
     entityId?: string;
     group?: MetadataGroupValueType;
@@ -646,7 +989,7 @@ export declare type ParsedSearchResultEntryTimespanType = {
     endSeconds?: number;
 };
 
-export declare type ParsedSearchResultEntryType = {
+declare type ParsedSearchResultEntryType = {
     entityType: 'Item' | 'Collection';
     entityId: string;
     events?: ParsedSearchResultEntryTimespanType[];
@@ -654,7 +997,7 @@ export declare type ParsedSearchResultEntryType = {
     collectionType?: CollectionType;
 };
 
-export declare type ParsedSearchResultEvents<TOptions> = TOptions extends {
+declare type ParsedSearchResultEvents<TOptions> = TOptions extends {
     flatEvents?: true;
 } ? ParsedSearchResultEntryTimespanType[] : ParsedSearchResultEntryType[];
 
@@ -975,13 +1318,15 @@ export declare const parseNowDate: (value?: string) => Date;
  * - https://apidoc.vidispine.com/latest/ref/search.html#search-collection-and-item-by-metadata-group
  * - https://apidoc.vidispine.com/latest/item/search.html#find-item-and-collections-by-their-metadata-groups
  *
- * @param searchResult
- * @param options
- * @returns
+ * @param searchResult Metadata-group search results that should be parsed into events
+ * @param options options for tweaking how search results should be parsed
+ * @returns Search results converted to an array of more event-like objects
+ *
+ * @category Search
  */
 export declare const parseSearchResultEvents: <TOptions extends ParseSearchResultEventsOptions = ParseSearchResultEventsOptions>(searchResult?: SearchResultType, options?: TOptions) => ParsedSearchResultEvents<TOptions>;
 
-export declare type ParseSearchResultEventsOptions = {
+declare type ParseSearchResultEventsOptions = {
     /**
      * Append matching group with metadata
      */
@@ -1014,7 +1359,21 @@ export declare type ParseSearchResultEventsOptions = {
  *
  * @category Shape
  */
-export declare const parseShapeType: (shapeType?: ShapeType) => ParsedShapeType;
+export declare const parseShapeType: (shapeType?: ShapeType, options?: ParseShapeTypeOptions) => ParsedShapeType;
+
+declare type ParseShapeTypeOptions = {
+    /**
+     * Which component type to prioritize when merging and duplicate keys in components
+     *
+     * Default priority:
+     * 1. 'container'
+     * 2. 'video'
+     * 3. 'audio'
+     * 4. 'binary'
+     *
+     */
+    priority?: ('container' | 'video' | 'audio' | 'binary')[];
+};
 
 /**
  * Parse simple (key/value) metadata
@@ -1114,6 +1473,13 @@ export declare type ParseValueOptions = {
  */
 export declare const parseVideoComponent: (videoComponentType?: VideoComponentType) => ParsedVideoComponentType;
 
+export declare type PlayerSource = {
+    src: string;
+    type: string;
+    label: string;
+    timeBase: string;
+};
+
 /**
  * Const object with VidiCore role names
  *
@@ -1248,6 +1614,21 @@ export declare const SHAPE_MEDIA_TYPES: {
 
 export declare type ShapeMediaType = keyof typeof SHAPE_MEDIA_TYPES;
 
+/**
+ * Chunked upload status types
+ *
+ * @category Upload
+ */
+export declare enum STATUSES {
+    transferring = 1,
+    paused = 2,
+    complete = 3,
+    failed = 4,
+    idle = 5,
+    canceled = 6,
+    offline = 7
+}
+
 /**
  * Array with all available VidiCore system/default field group names
  *
@@ -1404,14 +1785,15 @@ export declare class TimeCode {
      * Creates a new TimeCode instance with specified timeBase and samples adjusted to that.
      *
      * @remarks
-     * If it conforms to a less granular time base - it will floor samples (hasn't reached that sample yet)
+     * It floors samples when conforming to a less granular time base (can be changed with `options.mode`)
+     *
      * - e.g. "51@50".conformTo("PAL") => "25@PAL" (not "26@PAL")
      *
      * @param timeBase The TimeBase it should conform the TimeCode to
-     * @param options Explicitly set TimeCode options, by default these are derived from `timeBase`
+     * @param options Explicitly set conform options, by default these are derived from `timeBase`
      * @returns A new TimeCode instance with the conformTo timeBase applied
      */
-    conformTimeBase(timeBase: TimeCodeInput['timeBase'], options?: TimeCodeInputOptions): TimeCode;
+    conformTimeBase(timeBase: TimeCodeInput['timeBase'], options?: TimeCodeConformOptions): TimeCode;
     /**
      * Get TimeCode as a text representation
      *
@@ -1464,7 +1846,7 @@ export declare class TimeCode {
      *
      * @returns Total seconds for the time code
      */
-    toSeconds(): number;
+    toSeconds(options?: TimeCodeToSecondsOptions): number;
     /**
      * Get TimeCode in a duration representation
      *
@@ -1491,9 +1873,11 @@ export declare class TimeCode {
     /**
      * Get TimeCode in a smpte representation
      *
+     * @param {Object} options
+     * @param {boolean} options.uniformSeparators Use the frame separator for all separators in the smpte string
      * @returns Smpte representation of the TimeCode
      */
-    toSmpte(): string;
+    toSmpte(options?: ToSmpteOptions): string;
     /**
      * Get TimeCode as a VidiCore TimeCodeType object
      *
@@ -1514,11 +1898,19 @@ export declare class TimeCode {
     };
 }
 
+export declare interface TimeCodeConformOptions extends TimeCodeInputOptions {
+    /**
+     * Set if conforming should floor, round or ceil samples when converting to a less granular timebase
+     * @default `'floor'`
+     */
+    roundingMode?: 'floor' | 'ceil' | 'round';
+}
+
 export declare type TimeCodeInput = {
     /** Amount of samples for the time code */
     samples?: number | string;
     /** The time base for the time code */
-    timeBase?: string | TimeBaseInput | TimeBase;
+    timeBase?: string | number | TimeBaseInput | TimeBase;
 };
 
 export declare type TimeCodeInputOptions = {
@@ -1528,4 +1920,17 @@ export declare type TimeCodeInputOptions = {
     frameSeparator?: string;
 };
 
+declare type TimeCodeToSecondsOptions = {
+    /**
+     * Set true if seconds should be rounded with millisecond precision
+     *
+     * @default false
+     */
+    round?: boolean;
+};
+
+declare type ToSmpteOptions = {
+    uniformSeparators?: boolean;
+};
+
 export { }