@clockworkdog/cogs-client 2.11.2 → 3.0.0-alpha.1

package/dist/types/MediaSchema.d.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+export type TemporalProperties = z.infer<typeof TemporalProperties>;
+declare const TemporalProperties: z.ZodObject<{
+    t: z.ZodNumber;
+    rate: z.ZodNumber;
+}, z.core.$strip>;
+export type VisualProperties = z.infer<typeof VisualProperties>;
+declare const VisualProperties: z.ZodObject<{
+    opacity: z.ZodNumber;
+}, z.core.$strip>;
+export type AudialProperties = z.infer<typeof AudialProperties>;
+declare const AudialProperties: z.ZodObject<{
+    volume: z.ZodNumber;
+}, z.core.$strip>;
+export type ImageMetadata = z.infer<typeof ImageMetadata>;
+declare const ImageMetadata: z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    file: z.ZodString;
+    fit: z.ZodUnion<readonly [z.ZodLiteral<"contain">, z.ZodLiteral<"cover">, z.ZodLiteral<"none">]>;
+}, z.core.$strip>;
+export type AudioMetadata = z.infer<typeof AudioMetadata>;
+declare const AudioMetadata: z.ZodObject<{
+    type: z.ZodLiteral<"audio">;
+    file: z.ZodString;
+    audioOutput: z.ZodString;
+}, z.core.$strip>;
+export type VideoMetadata = z.infer<typeof VideoMetadata>;
+declare const VideoMetadata: z.ZodObject<{
+    type: z.ZodLiteral<"video">;
+    file: z.ZodString;
+    audioOutput: z.ZodString;
+    fit: z.ZodUnion<readonly [z.ZodLiteral<"contain">, z.ZodLiteral<"cover">, z.ZodLiteral<"none">]>;
+}, z.core.$strip>;
+export type NullKeyframe = z.infer<typeof NullKeyframe>;
+declare const NullKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodNull], null>;
+/**
+ * Keyframes are indexed by a timestamp given in ms
+ */
+export type InitialImageKeyframe = z.infer<typeof InitialImageKeyframe>;
+declare const InitialImageKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+    set: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], null>;
+/**
+ * Keyframes are indexed by a timestamp given in ms
+ */
+export type ImageKeyframe = z.infer<typeof ImageKeyframe>;
+declare const ImageKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+    set: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    lerp: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], null>;
+/**
+ * Keyframes are indexed by a timestamp given in ms
+ */
+export type InitialAudioKeyframe = z.infer<typeof InitialAudioKeyframe>;
+declare const InitialAudioKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+    set: z.ZodOptional<z.ZodObject<{
+        volume: z.ZodOptional<z.ZodNumber>;
+        t: z.ZodOptional<z.ZodNumber>;
+        rate: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], null>;
+/**
+ * Keyframes are indexed by a timestamp given in ms
+ */
+export type AudioKeyframe = z.infer<typeof AudioKeyframe>;
+declare const AudioKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+    set: z.ZodOptional<z.ZodObject<{
+        volume: z.ZodOptional<z.ZodNumber>;
+        t: z.ZodOptional<z.ZodNumber>;
+        rate: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    lerp: z.ZodOptional<z.ZodObject<{
+        volume: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], null>;
+/**
+ * Keyframes are indexed by a timestamp given in ms
+ */
+export type InitialVideoKeyframe = z.infer<typeof InitialVideoKeyframe>;
+declare const InitialVideoKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+    set: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodOptional<z.ZodNumber>;
+        volume: z.ZodOptional<z.ZodNumber>;
+        t: z.ZodOptional<z.ZodNumber>;
+        rate: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], null>;
+/**
+ * Keyframes are indexed by a timestamp given in ms
+ */
+export type VideoKeyframe = z.infer<typeof VideoKeyframe>;
+declare const VideoKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+    set: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodOptional<z.ZodNumber>;
+        volume: z.ZodOptional<z.ZodNumber>;
+        t: z.ZodOptional<z.ZodNumber>;
+        rate: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    lerp: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodOptional<z.ZodNumber>;
+        volume: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], null>;
+export declare const MediaSurfaceStateSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    keyframes: z.ZodTuple<[z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+        set: z.ZodOptional<z.ZodObject<{
+            opacity: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        lerp: z.ZodOptional<z.ZodObject<{
+            opacity: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], null>], z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+        set: z.ZodOptional<z.ZodObject<{
+            opacity: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], null>, z.ZodTuple<[z.ZodNumber, z.ZodNull], null>]>>;
+    type: z.ZodLiteral<"image">;
+    file: z.ZodString;
+    fit: z.ZodUnion<readonly [z.ZodLiteral<"contain">, z.ZodLiteral<"cover">, z.ZodLiteral<"none">]>;
+}, z.core.$strip>, z.ZodObject<{
+    keyframes: z.ZodTuple<[z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+        set: z.ZodOptional<z.ZodObject<{
+            volume: z.ZodOptional<z.ZodNumber>;
+            t: z.ZodOptional<z.ZodNumber>;
+            rate: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        lerp: z.ZodOptional<z.ZodObject<{
+            volume: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], null>], z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+        set: z.ZodOptional<z.ZodObject<{
+            volume: z.ZodOptional<z.ZodNumber>;
+            t: z.ZodOptional<z.ZodNumber>;
+            rate: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], null>, z.ZodTuple<[z.ZodNumber, z.ZodNull], null>]>>;
+    type: z.ZodLiteral<"audio">;
+    file: z.ZodString;
+    audioOutput: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    keyframes: z.ZodTuple<[z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+        set: z.ZodOptional<z.ZodObject<{
+            opacity: z.ZodOptional<z.ZodNumber>;
+            volume: z.ZodOptional<z.ZodNumber>;
+            t: z.ZodOptional<z.ZodNumber>;
+            rate: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        lerp: z.ZodOptional<z.ZodObject<{
+            opacity: z.ZodOptional<z.ZodNumber>;
+            volume: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], null>], z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodObject<{
+        set: z.ZodOptional<z.ZodObject<{
+            opacity: z.ZodOptional<z.ZodNumber>;
+            volume: z.ZodOptional<z.ZodNumber>;
+            t: z.ZodOptional<z.ZodNumber>;
+            rate: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], null>, z.ZodTuple<[z.ZodNumber, z.ZodNull], null>]>>;
+    type: z.ZodLiteral<"video">;
+    file: z.ZodString;
+    audioOutput: z.ZodString;
+    fit: z.ZodUnion<readonly [z.ZodLiteral<"contain">, z.ZodLiteral<"cover">, z.ZodLiteral<"none">]>;
+}, z.core.$strip>]>>;
+export type ImageOptions = VisualProperties;
+export type AudioOptions = TemporalProperties & AudialProperties;
+export type VideoOptions = TemporalProperties & VisualProperties & AudialProperties;
+export type ImageState = {
+    type: 'image';
+    file: string;
+    fit: 'cover' | 'contain' | 'none';
+    keyframes: [InitialImageKeyframe, ...Array<ImageKeyframe | NullKeyframe>];
+};
+export type AudioState = {
+    type: 'audio';
+    file: string;
+    audioOutput: string;
+    keyframes: [InitialAudioKeyframe, ...Array<AudioKeyframe | NullKeyframe>];
+};
+export type VideoState = {
+    type: 'video';
+    file: string;
+    fit: 'cover' | 'contain' | 'none';
+    audioOutput: string;
+    keyframes: [InitialVideoKeyframe, ...Array<VideoKeyframe | NullKeyframe>];
+};
+export type MediaClipState = ImageState | AudioState | VideoState;
+export type MediaSurfaceState = Record<string, MediaClipState>;
+export type UnionsEqual<A, B> = Exclude<A, B> extends never ? (Exclude<B, A> extends never ? true : false) : false;
+export declare const defaultImageOptions: ImageOptions;
+export declare const defaultAudioOptions: AudioOptions;
+export declare const defaultVideoOptions: VideoOptions;
+export {};

package/dist/types/MediaSchema.js

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+const TemporalProperties = z.object({
+    t: z.number().gte(0),
+    rate: z.number().gte(0),
+});
+const VisualProperties = z.object({
+    opacity: z.number().gte(0).lte(1),
+});
+const AudialProperties = z.object({
+    volume: z.number().gte(0).lte(1),
+});
+const ImageMetadata = z.object({
+    type: z.literal('image'),
+    file: z.string(),
+    fit: z.union([z.literal('contain'), z.literal('cover'), z.literal('none')]),
+});
+const AudioMetadata = z.object({
+    type: z.literal('audio'),
+    file: z.string(),
+    audioOutput: z.string(),
+});
+const VideoMetadata = z.object({
+    type: z.literal('video'),
+    file: z.string(),
+    audioOutput: z.string(),
+    fit: z.union([z.literal('contain'), z.literal('cover'), z.literal('none')]),
+});
+const NullKeyframe = z.tuple([z.number(), z.null()]);
+const InitialImageKeyframe = z.tuple([
+    z.number(),
+    z
+        .object({
+        set: z
+            .object({
+            ...VisualProperties.shape,
+        })
+            .partial(),
+    })
+        .partial(),
+]);
+const ImageKeyframe = z.tuple([
+    z.number(),
+    z
+        .object({
+        set: z
+            .object({
+            ...VisualProperties.shape,
+        })
+            .partial(),
+        lerp: z
+            .object({
+            ...VisualProperties.shape,
+        })
+            .partial(),
+    })
+        .partial(),
+]);
+const InitialAudioKeyframe = z.tuple([
+    z.number(),
+    z
+        .object({
+        set: z
+            .object({
+            ...TemporalProperties.shape,
+            ...AudialProperties.shape,
+        })
+            .partial(),
+    })
+        .partial(),
+]);
+const AudioKeyframe = z.tuple([
+    z.number(),
+    z
+        .object({
+        set: z
+            .object({
+            ...TemporalProperties.shape,
+            ...AudialProperties.shape,
+        })
+            .partial(),
+        lerp: z
+            .object({
+            ...AudialProperties.shape,
+        })
+            .partial(),
+    })
+        .partial(),
+]);
+const InitialVideoKeyframe = z.tuple([
+    z.number(),
+    z
+        .object({
+        set: z
+            .object({
+            ...TemporalProperties.shape,
+            ...AudialProperties.shape,
+            ...VisualProperties.shape,
+        })
+            .partial(),
+    })
+        .partial(),
+]);
+const VideoKeyframe = z.tuple([
+    z.number(),
+    z
+        .object({
+        set: z
+            .object({
+            ...TemporalProperties.shape,
+            ...AudialProperties.shape,
+            ...VisualProperties.shape,
+        })
+            .partial(),
+        lerp: z
+            .object({
+            ...AudialProperties.shape,
+            ...VisualProperties.shape,
+        })
+            .partial(),
+    })
+        .partial(),
+]);
+const ImageClip = z.object({
+    ...ImageMetadata.shape,
+    keyframes: z.tuple([ImageKeyframe], z.union([InitialImageKeyframe, NullKeyframe])),
+});
+const AudioClip = z.object({
+    ...AudioMetadata.shape,
+    keyframes: z.tuple([AudioKeyframe], z.union([InitialAudioKeyframe, NullKeyframe])),
+});
+const VideoClip = z.object({
+    ...VideoMetadata.shape,
+    keyframes: z.tuple([VideoKeyframe], z.union([InitialVideoKeyframe, NullKeyframe])),
+});
+export const MediaSurfaceStateSchema = z.record(z.string(), z.union([ImageClip, AudioClip, VideoClip]));
+true;
+true;
+true;
+true;
+export const defaultImageOptions = {
+    opacity: 1,
+};
+export const defaultAudioOptions = {
+    t: 0,
+    rate: 1,
+    volume: 1,
+};
+export const defaultVideoOptions = {
+    t: 0,
+    rate: 1,
+    volume: 1,
+    opacity: 1,
+};

package/dist/utils/getStateAtTime.d.ts

@@ -0,0 +1,28 @@
+import { MediaClipState, TemporalProperties } from '../types/MediaSchema';
+export declare function getStateAtTime<State extends MediaClipState>(state: State, time: number): State['keyframes'][0][1]['set'] | undefined;
+/**
+ * Goes through all keyframes to lerp between many different properties
+ * Note: This has no specific logic regarding types of properties
+ *       Do not use this for setting time / rate.
+ *       They behave differently in the schema. ( @see getTemporalPropertiesAtTime )
+ *
+ * @param keyframes keyframes from a given MediaClipState
+ * @param time the time (on or between keyframes) to calculate
+ * @returns a grouped object of all properties
+ */
+export declare function getPropertiesAtTime<P extends Record<string, unknown>>(keyframes: [number, {
+    set?: Partial<P>;
+    lerp?: Partial<P>;
+}][], time: number): P;
+/**
+ * Keep track of time whilst going through the keyframes at respective rate.
+ * Temporal properties cannot be interpolated in the media schema.
+ *
+ * @param keyframes temporal keyframes from an AudioClipState or VideoClipState
+ * @param time the time (on or between keyframes) to calculate
+ * @returns the temporal properties of the media at the given time
+ */
+export declare function getTemporalPropertiesAtTime<P extends TemporalProperties>(keyframes: [number, {
+    set?: Partial<P>;
+    lerp?: Partial<P>;
+}][], time: number): TemporalProperties | undefined;

package/dist/utils/getStateAtTime.js

@@ -0,0 +1,141 @@
+import { defaultAudioOptions, defaultImageOptions, defaultVideoOptions } from '../types/MediaSchema';
+export function getStateAtTime(state, time) {
+    switch (state.type) {
+        case 'image': {
+            const firstTimestamp = state.keyframes[0][0];
+            if (firstTimestamp > time) {
+                return undefined;
+            }
+            const nonNullKeyframes = state.keyframes.filter((k) => k[1] !== null);
+            const properties = getPropertiesAtTime(nonNullKeyframes, time);
+            return { ...defaultImageOptions, ...properties };
+        }
+        case 'audio': {
+            const nonNullKeyframes = state.keyframes.filter((k) => k[1] !== null);
+            const temporalProperties = getTemporalPropertiesAtTime(nonNullKeyframes, time);
+            if (!temporalProperties) {
+                return undefined;
+            }
+            const properties = getPropertiesAtTime(nonNullKeyframes, time);
+            return { ...defaultAudioOptions, ...properties, ...temporalProperties };
+        }
+        case 'video': {
+            const nonNullKeyframes = state.keyframes.filter((k) => k[1] !== null);
+            const temporalProperties = getTemporalPropertiesAtTime(nonNullKeyframes, time);
+            if (!temporalProperties) {
+                return undefined;
+            }
+            const properties = getPropertiesAtTime(nonNullKeyframes, time);
+            return { ...defaultVideoOptions, ...properties, ...temporalProperties };
+        }
+    }
+}
+/**
+ * Goes through all keyframes to lerp between many different properties
+ * Note: This has no specific logic regarding types of properties
+ *       Do not use this for setting time / rate.
+ *       They behave differently in the schema. ( @see getTemporalPropertiesAtTime )
+ *
+ * @param keyframes keyframes from a given MediaClipState
+ * @param time the time (on or between keyframes) to calculate
+ * @returns a grouped object of all properties
+ */
+export function getPropertiesAtTime(keyframes, time) {
+    const propertyKeyframes = {};
+    for (const [timestamp, properties] of keyframes) {
+        if (timestamp <= time) {
+            // If lerp and set are both present, we assume we lerp up until the timestamp,
+            // then set to a new value
+            Object.entries(properties.lerp ?? {}).forEach(([property, value]) => {
+                propertyKeyframes[property] ?? (propertyKeyframes[property] = {});
+                propertyKeyframes[property].before = [timestamp, value];
+            });
+            Object.entries(properties.set ?? {}).forEach(([property, value]) => {
+                propertyKeyframes[property] ?? (propertyKeyframes[property] = {});
+                propertyKeyframes[property].before = [timestamp, value];
+            });
+        }
+        else {
+            // We're trying to find the closest timestamp afterwards for lerping
+            // So only set if not yet set
+            Object.entries(properties.lerp ?? {}).forEach(([property, value]) => {
+                propertyKeyframes[property] ?? (propertyKeyframes[property] = {});
+                if (propertyKeyframes[property].after === undefined) {
+                    propertyKeyframes[property].after = [timestamp, value];
+                }
+            });
+        }
+    }
+    const properties = {};
+    Object.entries(propertyKeyframes).forEach(([property, { before, after }]) => {
+        // There is no lerping, and it has been set before
+        // It's a constant!
+        if (after === undefined && before) {
+            properties[property] = before[1];
+            return;
+        }
+        // Multiple timestamps on the same, we return after
+        if (before && after && before[0] === after[0]) {
+            properties[property] = after[1];
+            return;
+        }
+        // Property has been set, and there's a lerp timestamp afterwards
+        // We've got numbers, so lets try to linearly inerpolate
+        if (before && typeof before[1] === 'number' && after && typeof after[1] === 'number') {
+            properties[property] = (before[1] + ((time - before[0]) * (after[1] - before[1])) / (after[0] - before[0]));
+            return;
+        }
+    });
+    return properties;
+}
+/**
+ * Keep track of time whilst going through the keyframes at respective rate.
+ * Temporal properties cannot be interpolated in the media schema.
+ *
+ * @param keyframes temporal keyframes from an AudioClipState or VideoClipState
+ * @param time the time (on or between keyframes) to calculate
+ * @returns the temporal properties of the media at the given time
+ */
+export function getTemporalPropertiesAtTime(keyframes, time) {
+    // Not defined if the media starts in the future
+    const firstKeyframe = keyframes[0];
+    if (!firstKeyframe || firstKeyframe[0] > time) {
+        return undefined;
+    }
+    let timeAtLastKeyframe = 0;
+    let { t: mediaTimeAtLastKeyframe, rate: mediaRateAtLastKeyframe } = defaultAudioOptions;
+    for (const [timestamp, properties] of keyframes) {
+        // Only calculate up to the keyframe on or before
+        if (timestamp > time)
+            break;
+        const { set } = properties;
+        if (!set)
+            continue;
+        const { t, rate } = set;
+        // time is set - no calculations needed
+        if (t !== undefined) {
+            timeAtLastKeyframe = timestamp;
+            mediaTimeAtLastKeyframe = t;
+            if (rate !== undefined) {
+                mediaRateAtLastKeyframe = rate;
+            }
+            continue;
+        }
+        // rate is set on it's own, calculate how much time has passed
+        if (rate !== undefined) {
+            const duration = timestamp - timeAtLastKeyframe;
+            const mediaDuration = duration * mediaRateAtLastKeyframe;
+            timeAtLastKeyframe = timestamp;
+            mediaTimeAtLastKeyframe += mediaDuration;
+            mediaRateAtLastKeyframe = rate;
+        }
+    }
+    // Calculate time after last keyframe
+    const finalDuration = time - timeAtLastKeyframe;
+    const finalMediaDuration = finalDuration * mediaRateAtLastKeyframe;
+    const finalMediaTime = mediaTimeAtLastKeyframe + finalMediaDuration;
+    return {
+        rate: mediaRateAtLastKeyframe,
+        t: finalMediaTime,
+    };
+}

package/package.json

@@ -3,7 +3,7 @@
   "description": "Connect to COGS to build a custom Media Master",
   "author": "Clockwork Dog <info@clockwork.dog>",
   "homepage": "https://github.com/clockwork-dog/cogs-sdk/tree/main/packages/javascript",
-  "version": "2.11.2",
+  "version": "3.0.0-alpha.1",
   "keywords": [],
   "license": "MIT",
   "repository": {
@@ -30,12 +30,14 @@
     "build:browser": "vite build",
     "watch-build": "tsc -w",
     "build-docs": "typedoc --out ../../docs/javascript --name @clockworkdog/cogs-client src/index.ts",
-    "release": "yarn npm publish --access public"
+    "release": "yarn npm publish --access public",
+    "prerelease": "yarn npm publish --access public --tag=next"
   },
   "dependencies": {
-    "@clockworkdog/timesync": "^2.11.2",
+    "@clockworkdog/timesync": "^3.0.0-alpha.1",
     "howler": "clockwork-dog/howler.js#fix-looping-clips",
-    "reconnecting-websocket": "^4.4.0"
+    "reconnecting-websocket": "^4.4.0",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
@@ -52,5 +54,6 @@
     "typescript-eslint": "^8.18.1",
     "vite": "^7.1.12",
     "vitest": "^4.0.6"
-  }
+  },
+  "stableVersion": "0.0.0"
 }