@vidispine/vdt-js 23.1.0-pre.4 → 23.1.0

package/dist/index.d.ts

@@ -152,9 +152,13 @@ type InputGroup = {
 } & Partial<MetadataGroupValueType>;
 /** Input to create a timespan of */
 type InputTimespan = {
+    /** Start for timespan */
     start?: string | number;
+    /** End for timespan */
     end?: string | number;
+    /** Base for timespan (typically undefined) */
     base?: string;
+    /** Group or field metadata */
     [groupOrFieldName: string]: InputGroupsOrFields;
 };
 type CreateMetadataTypeInput = InputTimespan | InputTimespan[];
@@ -175,6 +179,7 @@ type ParsedValue<TOptions> = TOptions extends {
     value: string;
 } & ParsedValueAttributes;
 type ParseValueOptions = {
+    /** Include attributes on value (`true` for all) */
     includeValueAttributes?: boolean | (keyof ParsedValueAttributes)[];
 };
 
@@ -184,10 +189,12 @@ type ParsedValueList<TOptions> = TOptions extends {
 } ? string : TOptions extends {
     arrayOnSingleValue?: true;
 } ? ParsedValue<TOptions>[] : ParsedValue<TOptions> | ParsedValue<TOptions>[];
-type ParseValueListOptions = {
+interface ParseValueListOptions extends ParseValueOptions {
+    /** String to join the values, (e.g. `,`) */
     joinValue?: string;
+    /** Return values as array even if single value */
     arrayOnSingleValue?: boolean;
-} & ParseValueOptions;
+}
 
 type ParsedFieldAttributes = Partial<Omit<MetadataFieldValueType, 'value'>>;
 type ParsedFieldObject<TOptions> = {
@@ -196,15 +203,19 @@ type ParsedFieldObject<TOptions> = {
 type ParsedField<TOptions> = TOptions extends {
     includeFieldAttributes?: false;
 } ? ParsedValueList<TOptions> : ParsedFieldObject<TOptions>;
-type ParseFieldOptions = {
+interface ParseFieldOptions extends ParseValueListOptions {
+    /** Include attributes on field (`true` for all) */
     includeFieldAttributes?: boolean | (keyof ParsedFieldAttributes)[];
-} & ParseValueListOptions;
+}
 
-type ParseFieldListOptions = {
+interface ParseFieldListOptions extends ParseFieldOptions {
+    /** Return fields as list */
     fieldAsList?: boolean;
+    /** Return fields as array even if only one field */
     arrayOnSingleField?: boolean;
+    /** Return all fields flattened (Note: keys might be overridden) */
     overrideField?: boolean;
-} & ParseFieldOptions;
+}
 type ParsedFieldList<TOptions> = TOptions extends {
     fieldAsList?: true;
 } ? ParsedField<TOptions>[] : TOptions extends {
@@ -244,12 +255,16 @@ type ParsedFieldList<TOptions> = TOptions extends {
 declare const parseFieldList: <TOptions extends ParseFieldListOptions = ParseFieldListOptions>(fieldList: MetadataFieldValueType[], options?: TOptions) => ParsedFieldList<TOptions>;
 
 type ParsedGroupAttributes = Omit<MetadataGroupValueType, 'field' | 'group'>;
-type ParseGroupOptions = {
+interface ParseGroupOptions extends ParseFieldListOptions {
+    /** Include group attributes (`true` for all) */
     includeGroupAttributes?: boolean | (keyof ParsedGroupAttributes)[];
+    /** Return groups as list */
     groupAsList?: boolean;
+    /** Return groups as array even if only one group */
     arrayOnSingleGroup?: boolean;
+    /** Return all groups flattened (Note: keys might be overridden) */
     overrideGroup?: boolean;
-} & ParseFieldListOptions;
+}
 type ParsedGroup<TOptions> = ((TOptions extends {
     groupAsList?: true;
 } ? {
@@ -301,24 +316,14 @@ type ParsedGroupList<TOptions> = TOptions extends {
 declare const parseGroupList: <TOptions extends ParseGroupOptions = ParseGroupOptions>(groupList: MetadataGroupValueType[], options?: TOptions) => ParsedGroupList<TOptions>;
 
 type ParsedTimespanAttributes = Omit<MetadataType['timespan'][number], 'field' | 'group'>;
-/**
- * __includeTimespanAttributes__:
- * Include attributes on timespan
- * (Set `true` or "array of attribute keys" to include specific attributes)
- *
- * __arrayOnSingle__:
- * Return groups, fields and values as array if single
- *
- * __flat__:
- * Return a flat (no array) representation of the timespan (Note: fields/groups might be overridden)
- *
- * @defaultValue `{ includeTimespanAttributes: false, arrayOnSingle: true, flat: false }`
- */
-type ParseTimespanOptions = {
+interface ParseTimespanOptions extends ParseGroupListOptions {
+    /** Include attributes on timespan (`true` for all) */
     includeTimespanAttributes?: boolean | (keyof ParsedTimespanAttributes)[];
+    /** Return groups, fields, and values as array */
     arrayOnSingle?: boolean;
+    /** Flatten timespan, groups and fields (Note: keys might be overridden) */
     flat?: boolean;
-} & ParseGroupListOptions;
+}
 type ParsedTimespan<TOptions> = ((TOptions extends {
     groupAsList?: true;
 } ? {
@@ -359,13 +364,18 @@ type ParsedTimespanList<TOptions> = TOptions extends {
 } ? ParsedTimespan<TOptions> : {
     [timespanKey: string]: ParsedTimespan<TOptions>[];
 };
-type ParseTimespanListOptions = {
+interface ParseTimespanListOptions extends ParseTimespanOptions {
+    /** Return timespans as list */
     timespanAsList?: boolean;
+    /** String to join timespans with (defaults to '_') */
     joinTimespan?: string;
+    /** Sort timespanList by ascending start then end time */
     sortTimespan?: boolean;
+    /** Return a flat representation - only one timespan with groups/fields named the same as single - of the timespan list (Note: timespans/fields/groups can be overridden) */
     flat?: boolean;
+    /** Flatten timespans to one object with generic timespan having highest priority (Note: fields/groups might be overridden) */
     flatTimespan?: boolean;
-} & ParseTimespanOptions;
+}
 /**
  * Parses timespanList according to specified options.
  * The attributes can be targeted for each sub-type.
@@ -394,10 +404,12 @@ type ParsedMetadataType<TOptions> = (TOptions extends {
 }) & (TOptions extends {
     includeMetadataAttributes?: true | string[];
 } ? ParsedMetadataAttributes : {});
-type ParseMetadataTypeOptions = {
+interface ParseMetadataTypeOptions extends ParseTimespanListOptions {
+    /** Include metadata attributes (`true` for all) */
     includeMetadataAttributes?: boolean | (keyof ParsedMetadataAttributes)[];
+    /** Flatten timespans, groups and fields (Note: keys might be overridden) */
     flat?: boolean;
-} & ParseTimespanListOptions;
+}
 /**
  * Parses MetadataType according to specified options
  *
@@ -431,7 +443,9 @@ declare const parseSimpleMetadataType: (simpleMetadataType: SimpleMetadataType)
 };
 
 type MetadataTypeToWebVttOptions = {
+    /** Name of group containing subtitle field/text */
     subtitleGroup?: string;
+    /** Name of field (text) to use for the subtitles */
     subtitleField?: string;
 };
 /**
@@ -518,8 +532,11 @@ type ParsedFacetType = {
 declare const parseFacetType: (facetType?: FacetType[]) => ParsedFacetType;
 
 type ParseHighlightTimespanOptions = {
+    /** Return an array if there is a single value */
     arrayOnSingle?: boolean;
+    /** Return timespans as list */
     timespanAsList?: boolean;
+    /** String to join the values (e.g. `,`) */
     joinValue?: string;
 };
 type ParsedHighlightTimespan = {
@@ -537,12 +554,16 @@ type ParsedHighlightTimespan = {
  */
 declare const parseHighlightTimespan: (timespan: SearchResultEntryTimespanType, options: ParseHighlightTimespanOptions) => ParsedHighlightTimespan;
 
-type ParseHighlightTimespanListOptions = {
+interface ParseHighlightTimespanListOptions extends ParseHighlightTimespanOptions {
+    /** Return parsed timespan as list (in an array) */
     timespanAsList?: boolean;
+    /** Character to join the start/end time codes with */
     joinTimespan?: string;
+    /** Flatten to field-name/field-value (Note: field-values may be overwritten) */
     flat?: boolean;
+    /** Flatten timespan to object with start/end as key */
     flatTimespan?: boolean;
-} & ParseHighlightTimespanOptions;
+}
 /**
  * Parses highlight timespans from VidiCore into key/value object.
  * The attributes can be targeted for each sub-type.
@@ -671,7 +692,9 @@ type ParsedContainerComponentType = {
 declare const parseContainerComponent: (containerComponentType?: ContainerComponentType) => ParsedContainerComponentType;
 
 type TimeBaseInput = {
+    /** The numerator for the TimeBase */
     numerator?: number | string;
+    /** The denominator for the TimeBase */
     denominator?: number | string;
 };
 /**
@@ -682,7 +705,9 @@ type TimeBaseInput = {
  * @category Time
  */
 declare class TimeBase {
+    /** The numerator for the TimeBase */
     numerator: number;
+    /** The denominator for the TimeBase */
     denominator: number;
     /**
      * Constructor for TimeBase
@@ -707,31 +732,32 @@ declare class TimeBase {
      * @returns Text representation of the TimeBase
      */
     toText(options?: {
+        /** Show time base as constant (e.g. PAL) */
         constant?: boolean;
+        /** Show time base as fraction (25:1) even when numerator is 1 */
         fraction?: boolean;
     }): string;
     /**
      * Output TimeBase as frame rate (by default max 16 decimal places)
      *
      * @remarks
-     * For `options.fixed`:
-     * - `true` gives two decimal places
-     * - `false` gives max amount of decimal places
-     * - `number` gives that amount of decimal places
-     *
      * Default format: rate with two decimals if needed (i.e. decimals are > 0)
      *
-     * Option precedence (when all true): `constant` > `rounded` > `fixed`
+     * `rounded` has precedence over `fixed`
      *
-     * @param options For how to display it as rate
+     * @param options On how to return the rate
      *
      * @return Rate of the TimeBase
-     *
-     * @category Time
      */
     toRate(options?: {
-        fixed?: boolean | number;
+        /** Rounded to nearest integer */
         rounded?: boolean;
+        /** Amount of decimal places
+         * - `true` two decimal places
+         * - `false` max amount of decimal places
+         * - `number` that amount of decimal places
+         */
+        fixed?: boolean | number;
     }): number;
     /**
      * Get TimeBase in a object representation
@@ -778,11 +804,15 @@ declare const formatTimeBaseText: (timeBaseText?: string | number) => TimeBase;
 declare const formatTimeBaseType: (timeBase: TimeBaseInput) => TimeBase;
 
 type TimeCodeInput = {
+    /** Amount of samples for the time code */
     samples?: number | string;
+    /** The time base for the time code */
     timeBase?: string | TimeBaseInput | TimeBase;
 };
 type TimeCodeInputOptions = {
+    /** If time code is dropFrame or not (by default checks timeBase) */
     dropFrame?: boolean;
+    /** Separator for frame in smpte output (default ":" for non-drop-frame and ";" for dropFrame) */
     frameSeparator?: string;
 };
 /**
@@ -793,9 +823,13 @@ type TimeCodeInputOptions = {
  * @category Time
  */
 declare class TimeCode {
+    /** Amount of samples for the time code */
     samples: number;
+    /** The time base for the time code */
     timeBase: TimeBase;
+    /** If time code is dropFrame or not (by default checks timeBase) */
     dropFrame?: boolean;
+    /** Separator for frame in smpte output (default ":" for non-drop-frame and ";" for dropFrame) */
     frameSeparator?: string;
     /**
      * Constructor for TimeCode
@@ -806,12 +840,15 @@ declare class TimeCode {
     constructor(timeCodeType: TimeCodeInput, options?: TimeCodeInputOptions);
     /**
      * Return this TimeCode added with the supplied timeCodeType
-     * If time bases differ, it will retain the time base of this TimeCode instance
-     * If supplied time code has a more granular time base - it will round down exceeding samples (hasn't reached that sample yet)
+     * - If time bases differ, it will retain the time base of this TimeCode instance
+     * - If supplied time code has a more granular time base, it will round down exceeding samples (hasn't reached that sample yet)
+     *
+     * @remarks
+     * If you don't want to "lose" frames in the manner described above, make sure time code you're operating on has higher time base granularity
      *
-     * Note: This might make you "lose" frames depending on granularity of time bases, e.g.
-     * "51@50".add("25@25") => "101@50"
-     * while "25@25".add("51@50") => "50@25" (not "101@50")
+     * To exemplify:
+     * - "51@50".add("25@25") => "101@50"
+     * - while "25@25".add("51@50") => "50@25"
      *
      * @param timeCode A TimeCode instance you want to add with
      * @returns A new TimeCode instance with the addition applied
@@ -819,12 +856,15 @@ declare class TimeCode {
     add(timeCode: TimeCode): TimeCode;
     /**
      * Return this TimeCode subtracted with the supplied timeCodeType
-     * If time bases differ, it will retain the time base of the instance time code
-     * If supplied time code has a more granular time base - it will round down exceeding samples (hasn't reached that sample yet)
+     * - If time bases differ, it will retain the time base of the instance time code
+     * - If supplied time code has a more granular time base, it will round down exceeding samples (hasn't reached that sample yet)
      *
-     * Note: This might make you "lose" frames depending on granularity of time bases, e.g.
-     * "101@50".subtract("25@25") => "51@50"
-     * while "50@25".subtract("51@50") => "25@25" (not "49@50")
+     * @remarks
+     * If you don't want to "lose" frames in the manner described above, make sure time code you're operating on has higher time base granularity
+  
+     * To exemplify:
+     * - "101@50".subtract("25@25") => "51@50"
+     * - while "50@25".subtract("51@50") => "25@25"
      *
      * @param timeCode A TimeCode instance you want to subtract with
      * @returns A new TimeCode instance with the subtraction applied
@@ -833,29 +873,32 @@ 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)
      * - 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`
      * @returns A new TimeCode instance with the conformTo timeBase applied
      */
-    conformTimeBase(timeBase: TimeCodeInput['timeBase']): TimeCode;
+    conformTimeBase(timeBase: TimeCodeInput['timeBase'], options?: TimeCodeInputOptions): TimeCode;
     /**
      * Get TimeCode as a text representation
      *
      * @remarks
-     * Default format: samples@denominator(:numerator if > 1)
+     * Default format: `samples@denominator[:numerator (if > 1)])`
      *
      * `constant` has precedence over `fraction` if both are true
      *
      * @param options Options for how to format text
      * @returns Text representation of TimeCode
-     *
-     * @category Time
      */
     toText(options?: {
+        /** Include time base even if seconds (i.e. append @1 or @1:1) */
         includeTimeBaseForSeconds?: boolean;
+        /** show as constant (e.g. @PAL) */
         constant?: boolean;
+        /** show as fraction (e.g. @25:1) */
         fraction?: boolean;
     }): string;
     /**
@@ -871,7 +914,8 @@ declare class TimeCode {
     };
     /**
      * Get TimeCode in a time object representation
-     * "milliseconds" is rounded down, if you want another representation use "partialSeconds"
+     *
+     * Note: "milliseconds" is rounded down - use "partialSeconds" for another representation
      *
      * @returns Time for the time code
      */
@@ -890,14 +934,15 @@ declare class TimeCode {
     toSeconds(): number;
     /**
      * Get TimeCode in a duration representation
-     * The time unit char keys for the format string are:
-     * - "h" for hour
-     * - "m" for minute
-     * - "s" for seconds
-     * - "S" for milliseconds
-     * Any other char will be kept in the duration output string.
      *
-     * Add consecutive chars for zero padding.
+     * The time unit keys for the format string are:
+     * - `h` for hour
+     * - `m` for minute
+     * - `s` for seconds
+     * - `S` for milliseconds
+     * - Any other char will be kept in the duration output string
+     *
+     * Note: Add several consecutive chars for zero padding.
      *
      * By default it:
      * - uses colon delimiter (e.g. for format "hhmmss")
@@ -907,6 +952,7 @@ declare class TimeCode {
      * @returns Duration representation of the TimeCode
      */
     toDuration(options?: {
+        /** Specify format of duration string, (e.g. `hh:mm:ss.S` for "01:23:04.5") */
         format?: string;
     }): string;
     /**
@@ -935,10 +981,20 @@ declare class TimeCode {
     };
 }
 
-type FormatTimeCodeSecondsOptions = {
+interface FormatTimeCodeSecondsOptions extends TimeCodeInputOptions {
+    /**
+     * The TimeBase the output TimeCode should have
+     *
+     * Note: if unset and useGCD=false, denominator will be 10^(amount-of-decimals)
+     */
     timeBase?: number | string | TimeBaseInput;
+    /**
+     * Samples and denominator are divided with GCD
+     *
+     * e.g. `1.04 => 104@100 => 26@25` (if no explicit `timeBase` is set)
+     */
     useGCD?: boolean;
-} & TimeCodeInputOptions;
+}
 /**
  * Format seconds to TimeCode object
  *
@@ -958,19 +1014,19 @@ type FormatTimeCodeSecondsOptions = {
  */
 declare const formatTimeCodeSeconds: (seconds: string | number, options?: FormatTimeCodeSecondsOptions) => TimeCode;
 
-type FormatTimeCodeSmpteOptions = {
+interface FormatTimeCodeSmpteOptions extends TimeCodeInputOptions {
+    /** TimeBase of smpte (and consequently TimeBase of output TimeCode) */
     timeBase?: number | string | TimeBaseInput;
+    /** How to handle exceeding values (default `error`) */
     exceedingMode?: 'add' | 'ignore' | 'error';
-    dropFrame?: boolean;
-    frameSeparator?: string;
-} & Omit<TimeCodeInputOptions, 'dropFrame' | ' frameSeparator'>;
+}
 /**
  * Format smpte text to a TimeCode Instance
  *
- * exceedingMode:
- * - "overflow" exceeding values will be kept (e.g. PAL and 00:00:00:25 => 00:00:01:00)
- * - "truncate" exceeding values will be truncated (e.g. PAL and 00:00:00:25 => 00:00:00:24)
- * - "error" exceeding values will throw error (e.g. PAL and 00:00:00:25 => Error)
+ * Options for `exceedingMode`:
+ * - `add` will be overflow to higher unit (e.g. PAL and 00:00:00:25 => 00:00:01:00)
+ * - `ignore` will be truncated (e.g. PAL and 00:00:00:25 => 00:00:00:24)
+ * - `error` will throw error (e.g. PAL and 00:00:00:25 => Error)
  *
  * @param smpte String representation of smpte
  * @param options Options for creating the time code from smpte
@@ -980,9 +1036,10 @@ type FormatTimeCodeSmpteOptions = {
  */
 declare const formatTimeCodeSmpte: (smpte: string, options?: FormatTimeCodeSmpteOptions) => TimeCode;
 
-type FormatTimeCodeTextOptions = {
+interface FormatTimeCodeTextOptions extends TimeCodeInputOptions {
+    /** The time base the returned TimeCode should have */
     timeBase?: number | string | TimeBaseInput;
-} & TimeCodeInputOptions;
+}
 /**
  * Format text to a TimeCode instance
  *
@@ -1129,7 +1186,7 @@ type FilterShapeSourceOption = {
  *
  * @category Shape
  */
-declare const filterShapeSource: (itemType: ItemType, options: FilterShapeSourceOption) => FilteredShapeListObject[];
+declare const filterShapeSource: (itemType: ItemType, options?: FilterShapeSourceOption) => FilteredShapeListObject[];
 
 type ShapeMediaType = keyof typeof SHAPE_MEDIA_TYPES;
 /**