@arcanewizards/timecode-toolbox 0.0.3

package/src/components/proto.ts

@@ -0,0 +1,420 @@
+import z from 'zod';
+import {
+  AnyComponentProto,
+  BaseClientComponentCall,
+  BaseClientComponentMessage,
+  BaseComponentProto,
+} from '@arcanejs/protocol';
+import { SIGIL_COLOR, SigilColor } from '@arcanewizards/sigil/frontend/styling';
+import { Diff } from '@arcanejs/diff';
+import { NetworkInterface } from '@arcanewizards/net-utils';
+import { TimecodeMode } from '@arcanewizards/artnet/constants';
+import { Tree } from '../tree';
+
+/* Shared config & proto definitions */
+
+const NET_UTILS_GENERAL_TARGET_DEFINITION = z
+  .union([
+    z.object({
+      type: z.literal('host'),
+      host: z.string(),
+    }),
+    z.object({
+      type: z.literal('interface'),
+      interface: z.string(),
+    }),
+  ])
+  .and(
+    z.object({
+      port: z.number().optional(),
+    }),
+  );
+
+const INPUT_ARTNET_DEFINITION = z.object({
+  type: z.literal('artnet'),
+  iface: z.string(),
+  port: z.number().optional(),
+});
+
+export type InputArtnetDefinition = z.infer<typeof INPUT_ARTNET_DEFINITION>;
+
+export const isInputArtnetDefinition = (
+  definition: InputDefinition,
+): definition is InputArtnetDefinition => definition.type === 'artnet';
+
+const OUTPUT_ARTNET_DEFINITION = z.object({
+  type: z.literal('artnet'),
+  target: NET_UTILS_GENERAL_TARGET_DEFINITION,
+  mode: z.enum(['FILM', 'EBU', 'DF', 'SMPTE']),
+});
+
+export type OutputArtnetDefinition = z.infer<typeof OUTPUT_ARTNET_DEFINITION>;
+
+export const isOutputArtnetDefinition = (
+  definition: OutputDefinition,
+): definition is OutputArtnetDefinition => definition.type === 'artnet';
+
+const INPUT_OR_OUTPUT_TCNET_DEFINITION = z.object({
+  type: z.literal('tcnet'),
+  iface: z.string(),
+  nodeName: z.string().optional(),
+});
+
+export type InputTcnetDefinition = z.infer<
+  typeof INPUT_OR_OUTPUT_TCNET_DEFINITION
+>;
+
+export const isInputTcnetDefinition = (
+  definition: InputDefinition,
+): definition is InputTcnetDefinition => definition.type === 'tcnet';
+
+const INPUT_DEFINITION = z.union([
+  INPUT_ARTNET_DEFINITION,
+  INPUT_OR_OUTPUT_TCNET_DEFINITION,
+]);
+
+export type InputDefinition = z.infer<typeof INPUT_DEFINITION>;
+
+const INPUT_CONFIG = z.object({
+  name: z.string().optional(),
+  color: SIGIL_COLOR.optional(),
+  definition: INPUT_DEFINITION,
+  enabled: z.boolean(),
+  delayMs: z.number().optional(),
+});
+
+export type InputConfig = z.infer<typeof INPUT_CONFIG>;
+
+const GENERATOR_CLOCK_DEFINITION = z.object({
+  type: z.literal('clock'),
+  speed: z.number(),
+});
+
+export type GeneratorClockDefinition = z.infer<
+  typeof GENERATOR_CLOCK_DEFINITION
+>;
+
+const GENERATOR_DEFINITION = GENERATOR_CLOCK_DEFINITION;
+
+export type GeneratorDefinition = z.infer<typeof GENERATOR_DEFINITION>;
+
+const GENERATOR_CONFIG = z.object({
+  name: z.string().optional(),
+  color: SIGIL_COLOR.optional(),
+  delayMs: z.number().optional(),
+  definition: GENERATOR_DEFINITION,
+});
+
+export type GeneratorConfig = z.infer<typeof GENERATOR_CONFIG>;
+
+const OUTPUT_DEFINITION = OUTPUT_ARTNET_DEFINITION; // todo expand to other output types in the future
+
+export type OutputDefinition = z.infer<typeof OUTPUT_DEFINITION>;
+
+export type InputInstanceId = [
+  type: 'input',
+  rootId: string,
+  ...path: string[],
+];
+
+export const isInputInstanceId = (value: string[]): value is InputInstanceId =>
+  value.length >= 2 && value[0] === 'input';
+
+export const INPUT_INSTANCE_ID = z
+  .string()
+  .array()
+  // TODO: remove type coercion zod/v4
+  .refine(isInputInstanceId) as unknown as z.ZodType<InputInstanceId>;
+
+export type GeneratorInstanceId = [
+  type: 'generator',
+  rootId: string,
+  ...path: string[],
+];
+
+export const isGeneratorInstanceId = (
+  value: string[],
+): value is GeneratorInstanceId =>
+  value.length >= 2 && value[0] === 'generator';
+
+export const GENERATOR_INSTANCE_ID = z
+  .string()
+  .array()
+  // TODO: remove type coercion zod/v4
+  .refine(isGeneratorInstanceId) as unknown as z.ZodType<GeneratorInstanceId>;
+
+export type OutputInstanceId = [
+  type: 'output',
+  rootId: string,
+  ...path: string[],
+];
+
+export const isOutputInstanceId = (
+  value: string[],
+): value is OutputInstanceId => value.length >= 2 && value[0] === 'output';
+
+export const OUTPUT_INSTANCE_ID = z
+  .string()
+  .array()
+  // TODO: remove type coercion zod/v4
+  .refine(isOutputInstanceId) as unknown as z.ZodType<OutputInstanceId>;
+
+export const INPUT_OR_GENERATOR_INSTANCE_ID = z.union([
+  INPUT_INSTANCE_ID,
+  GENERATOR_INSTANCE_ID,
+]);
+
+export type InputOrGenInstance = z.infer<typeof INPUT_OR_GENERATOR_INSTANCE_ID>;
+
+export const TIMECODE_INSTANCE_ID = z.union([
+  INPUT_INSTANCE_ID,
+  GENERATOR_INSTANCE_ID,
+  OUTPUT_INSTANCE_ID,
+]);
+
+export type TimecodeInstanceId = z.infer<typeof TIMECODE_INSTANCE_ID>;
+
+const OUTPUT_CONFIG = z.object({
+  name: z.string().optional(),
+  color: SIGIL_COLOR.optional(),
+  definition: OUTPUT_DEFINITION,
+  enabled: z.boolean(),
+  delayMs: z.number().optional(),
+  link: INPUT_OR_GENERATOR_INSTANCE_ID.nullable(),
+});
+
+export type OutputConfig = z.infer<typeof OUTPUT_CONFIG>;
+
+export const TOOLBOX_CONFIG = z.object({
+  inputs: z.record(z.string(), INPUT_CONFIG),
+  generators: z.record(z.string(), GENERATOR_CONFIG),
+  outputs: z.record(z.string(), OUTPUT_CONFIG),
+});
+
+export type ToolboxConfig = z.infer<typeof TOOLBOX_CONFIG>;
+
+export const DEFAULT_CONFIG: ToolboxConfig = {
+  inputs: {},
+  generators: {},
+  outputs: {},
+};
+
+/* App State */
+
+export type TimecodePlayStateNone = {
+  state: 'none';
+};
+
+export type TimecodePlayStateStopped = {
+  state: 'stopped';
+  positionMillis: number;
+};
+
+export type TimecodePlayStatePlayingOrLagging = {
+  state: 'playing' | 'lagging';
+  effectiveStartTimeMillis: number;
+  /**
+   * 1 = real-time, 2 = twice as fast, 0.5 = half as fast, etc.
+   */
+  speed: number;
+};
+
+export type TimecodePlayState =
+  | TimecodePlayStateNone
+  | TimecodePlayStateStopped
+  | TimecodePlayStatePlayingOrLagging;
+
+export const isPlaying = (
+  state: TimecodePlayState,
+): state is TimecodePlayStatePlayingOrLagging =>
+  state.state === 'playing' || state.state === 'lagging';
+
+export const isStopped = (
+  state: TimecodePlayState,
+): state is TimecodePlayStateStopped => state.state === 'stopped';
+
+export type TimecodeState = {
+  /**
+   * Approximate accuracy of the timecode, if available
+   */
+  accuracyMillis: number | null;
+  /**
+   * SMPTE mode if known and applicable, otherwise null
+   */
+  smpteMode: TimecodeMode | null;
+  /**
+   * If supported, whether the source is currently on air
+   * (e.g. have a mixer value high enough)
+   */
+  onAir: boolean | null;
+} & TimecodePlayState;
+
+export type TimecodeTotalTime = {
+  timeMillis: number;
+  /**
+   * How accurate is the totalTimeMillis value,
+   * some sources (such as ShowKontrol) are not completely accurate.
+   */
+  precisionMillis: number;
+};
+
+export type TimecodeMetadata = {
+  /**
+   * If available, the total time of the track loaded in this timecode.
+   *
+   * Some timecode sources will not have this information.
+   */
+  totalTime: TimecodeTotalTime | null;
+  title: string | null;
+  artist: string | null;
+};
+
+export type TimecodeInstance = {
+  name: string | null;
+  errors?: string[];
+  warnings?: string[];
+  state: TimecodeState;
+  metadata: TimecodeMetadata | null;
+};
+
+export const isTimecodeInstance = (
+  instance: TimecodeInstance | TimecodeGroup | null,
+): instance is TimecodeInstance =>
+  instance !== null && 'state' in instance && 'metadata' in instance;
+
+export type TimecodeGroup = {
+  name: string | null;
+  color: SigilColor | null;
+  timecodes: Record<string, TimecodeInstance | TimecodeGroup>;
+};
+
+export const isTimecodeGroup = (
+  instance: TimecodeInstance | TimecodeGroup | null,
+): instance is TimecodeGroup => instance !== null && 'timecodes' in instance;
+
+export type ConnectedClient = {
+  name: string;
+  host: string;
+  port: number;
+  protocolVersion: string;
+  details: string[];
+};
+
+export type InputState = {
+  status: 'disabled' | 'connecting' | 'error' | 'active';
+  errors?: string[];
+  warnings?: string[];
+  timecode: TimecodeInstance | TimecodeGroup | null;
+  /**
+   * If applicable, details of any connected clients
+   */
+  clients?: ConnectedClient[];
+};
+
+export type GeneratorState = {
+  timecode: TimecodeInstance | null;
+};
+
+export type OutputState = {
+  status: 'disabled' | 'connecting' | 'error' | 'active';
+  errors?: string[];
+  warnings?: string[];
+  /**
+   * If applicable, details of any connected clients
+   */
+  clients?: ConnectedClient[];
+};
+
+export type ApplicationState = {
+  inputs: Record<string, InputState>;
+  generators: Record<string, GeneratorState>;
+  outputs: Record<string, OutputState>;
+};
+
+export type TimecodeHandlerMethods = {
+  play?: () => void;
+  pause?: () => void;
+  seekRelative?: (deltaMillis: number) => void;
+  beginning?: () => void;
+};
+
+export type AvailableHandlers = Partial<
+  Record<keyof TimecodeHandlerMethods, true>
+>;
+
+/* Proto */
+
+export const NAMESPACE = 'timecode-toolbox';
+
+export type Namespace = typeof NAMESPACE;
+
+export type ToolboxRootComponent = BaseComponentProto<
+  Namespace,
+  'toolbox-root'
+> & {
+  config: ToolboxConfig;
+  state: ApplicationState;
+  handlers: Tree<AvailableHandlers>;
+};
+
+export type TimecodeToolboxComponent = ToolboxRootComponent;
+
+export const isTimecodeToolboxComponent = (
+  component: AnyComponentProto,
+): component is TimecodeToolboxComponent => component.namespace === NAMESPACE;
+
+export type ToolboxRootGetNetworkInterfaces = BaseClientComponentCall<
+  Namespace,
+  'toolbox-root-get-network-interfaces'
+>;
+
+export type ToolboxRootGetNetworkInterfacesReturn = Record<
+  string,
+  NetworkInterface
+>;
+
+export type ToolboxRootCallHandler<
+  H extends keyof AvailableHandlers = keyof AvailableHandlers,
+> = BaseClientComponentCall<Namespace, 'toolbox-root-call-handler'> & {
+  path: string[];
+  handler: H;
+  args: Parameters<NonNullable<TimecodeHandlerMethods[H]>>;
+};
+
+export type ToolboxRootCallHandlerReturn = void;
+
+export type TimecodeToolboxComponentCalls = {
+  'toolbox-root-get-network-interfaces': {
+    call: ToolboxRootGetNetworkInterfaces;
+    return: ToolboxRootGetNetworkInterfacesReturn;
+  };
+  'toolbox-root-call-handler': {
+    call: ToolboxRootCallHandler;
+    return: ToolboxRootCallHandlerReturn;
+  };
+};
+
+export type ToolboxRootConfigUpdate = BaseClientComponentMessage<Namespace> & {
+  component: 'toolbox-root';
+  action: 'update-config';
+  diff: Diff<ToolboxConfig>;
+};
+
+export type TimecodeToolboxComponentMessage = ToolboxRootConfigUpdate;
+
+export const isTimecodeToolboxComponentMessage = <
+  C extends TimecodeToolboxComponentMessage['component'],
+>(
+  message: BaseClientComponentMessage<string>,
+  component: C,
+): message is TimecodeToolboxComponentMessage & { component: C } =>
+  message.namespace === NAMESPACE &&
+  (message as TimecodeToolboxComponentMessage).component === component;
+
+export const isTimecodeToolboxComponentCall = <
+  A extends keyof TimecodeToolboxComponentCalls,
+>(
+  call: BaseClientComponentCall<string, string>,
+  action: A,
+): call is TimecodeToolboxComponentCalls[A]['call'] =>
+  call.namespace === NAMESPACE && call.action === action;

package/src/config.ts

@@ -0,0 +1,7 @@
+import { createDataFileDefinition } from '@arcanejs/react-toolkit/data';
+import { DEFAULT_CONFIG, TOOLBOX_CONFIG } from './components/proto';
+
+export const ToolboxConfigData = createDataFileDefinition({
+  schema: TOOLBOX_CONFIG,
+  defaultValue: DEFAULT_CONFIG,
+});

package/src/generators/clock.tsx

@@ -0,0 +1,206 @@
+import {
+  FC,
+  ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import {
+  GeneratorClockDefinition,
+  GeneratorConfig,
+  InputOrGenInstance,
+  isPlaying,
+  isStopped,
+  TimecodePlayState,
+} from '../components/proto';
+import { useDataFileData } from '@arcanejs/react-toolkit/data';
+import { ToolboxConfigData } from '../config';
+import { HandlersUpdater, StateSensitiveComponentProps } from '../types';
+import { deleteTreePath, updateTreeState } from '../tree';
+
+type ClockGeneratorProps = StateSensitiveComponentProps & {
+  uuid: string;
+  config: GeneratorConfig;
+  generator: GeneratorClockDefinition;
+  setHandlers: HandlersUpdater;
+};
+
+export const ClockGenerator: FC<ClockGeneratorProps> = ({
+  uuid,
+  config,
+  generator,
+  setState,
+  setHandlers,
+}) => {
+  const id: InputOrGenInstance = useMemo(() => ['generator', uuid], [uuid]);
+
+  const [state, setLocalState] = useState<TimecodePlayState>({
+    state: 'stopped',
+    positionMillis: 0,
+  });
+
+  const { speed } = generator;
+
+  const play = useCallback(() => {
+    setLocalState((current) => {
+      if (isPlaying(current)) {
+        return current;
+      }
+      const positionMillis = isStopped(current) ? current.positionMillis : 0;
+      const effectiveStartTimeMillis = Date.now() - positionMillis / speed;
+      return {
+        state: 'playing',
+        effectiveStartTimeMillis,
+        speed,
+      };
+    });
+  }, [speed]);
+
+  const pause = useCallback(() => {
+    setLocalState((current) => {
+      if (!isPlaying(current)) {
+        return current;
+      }
+      const positionMillis =
+        (Date.now() - current.effectiveStartTimeMillis) * speed;
+      return {
+        state: 'stopped',
+        positionMillis,
+      };
+    });
+  }, [speed]);
+
+  const seekRelative = useCallback(
+    (deltaMillis: number) => {
+      setLocalState((current) => {
+        if (current.state === 'none') {
+          return current;
+        }
+        const now = Date.now();
+        const positionMillis = isPlaying(current)
+          ? (now - current.effectiveStartTimeMillis) * speed
+          : current.positionMillis;
+        const newPositionMillis = Math.max(positionMillis + deltaMillis, 0);
+        if (isPlaying(current)) {
+          const effectiveStartTimeMillis = now - newPositionMillis / speed;
+          return {
+            ...current,
+            effectiveStartTimeMillis,
+          };
+        } else {
+          return {
+            ...current,
+            positionMillis: newPositionMillis,
+          };
+        }
+      });
+    },
+    [speed],
+  );
+
+  const beginning = useCallback(() => {
+    setLocalState((current) => {
+      if (current.state === 'none') {
+        return current;
+      }
+      if (isPlaying(current)) {
+        const effectiveStartTimeMillis = Date.now();
+        return {
+          ...current,
+          effectiveStartTimeMillis,
+        };
+      } else {
+        return {
+          ...current,
+          positionMillis: 0,
+        };
+      }
+    });
+  }, []);
+
+  useEffect(() => {
+    setLocalState((current) => {
+      if (current.state === 'none' || current.state === 'stopped') {
+        return current;
+      }
+      const now = Date.now();
+      const positionMillis =
+        (now - current.effectiveStartTimeMillis) * current.speed;
+      const effectiveStartTimeMillis = now - positionMillis / speed;
+      return {
+        ...current,
+        effectiveStartTimeMillis,
+        speed,
+      };
+    });
+  }, [speed]);
+
+  useEffect(() => {
+    setHandlers((current) =>
+      updateTreeState(current, id, { play, pause, seekRelative, beginning }),
+    );
+  }, [setHandlers, id, play, pause, seekRelative, beginning]);
+
+  useEffect(
+    () =>
+      setState((current) => ({
+        ...current,
+        generators: {
+          ...current.generators,
+          [uuid]: {
+            timecode: {
+              metadata: null,
+              name: null,
+              state: {
+                accuracyMillis: null,
+                smpteMode: null,
+                onAir: null,
+                ...state,
+              },
+            },
+          },
+        },
+      })),
+    [setState, uuid, state, config.name],
+  );
+
+  useEffect(
+    () => () => {
+      setState((current) => {
+        const { [uuid]: _, ...rest } = current.generators;
+        return {
+          ...current,
+          generators: rest,
+        };
+      });
+      setHandlers((current) => deleteTreePath(current, id));
+    },
+    [setState, setHandlers, id, uuid],
+  );
+
+  return null;
+};
+
+type ClockGeneratorsProps = StateSensitiveComponentProps & {
+  setHandlers: HandlersUpdater;
+};
+
+export const ClockGenerators: FC<ClockGeneratorsProps> = (props) => {
+  const { generators } = useDataFileData(ToolboxConfigData);
+  return Object.entries(generators).map<ReactNode>(([uuid, input]) => {
+    const generator = input.definition;
+    if (generator.type !== 'clock') {
+      return null;
+    }
+    return (
+      <ClockGenerator
+        key={uuid}
+        uuid={uuid}
+        config={input}
+        generator={generator}
+        {...props}
+      />
+    );
+  });
+};

package/src/generators/index.tsx

@@ -0,0 +1,15 @@
+import { FC } from 'react';
+import { ClockGenerators } from './clock';
+import { HandlersUpdater, StateSensitiveComponentProps } from '../types';
+
+type GeneratorsProps = StateSensitiveComponentProps & {
+  setHandlers: HandlersUpdater;
+};
+
+export const Generators: FC<GeneratorsProps> = (props) => {
+  return (
+    <>
+      <ClockGenerators {...props} />
+    </>
+  );
+};

package/src/index.ts

@@ -0,0 +1,38 @@
+import { CoreComponents } from '@arcanejs/react-toolkit';
+import {
+  runSigilApp,
+  SigilAppInstance,
+  SIGIL_COMPONENTS,
+} from '@arcanewizards/sigil';
+import { ToolkitOptions } from '@arcanejs/toolkit';
+import pino from 'pino';
+import { AppApi, createApp, TimecodeToolboxAppProps } from './app';
+import { C } from './components/backend';
+import { version } from '../package.json';
+
+export type { AppApi };
+
+export * as urls from './urls';
+
+export type TimecodeToolboxOptions = {
+  logger: pino.Logger;
+  appProps: TimecodeToolboxAppProps;
+  toolkitOptions?: Omit<Partial<ToolkitOptions>, 'logger'>;
+  title: string;
+};
+
+export const runTimecodeToolboxServer = ({
+  logger,
+  appProps,
+  toolkitOptions,
+  title,
+}: TimecodeToolboxOptions): SigilAppInstance<AppApi> =>
+  runSigilApp<AppApi, TimecodeToolboxAppProps>({
+    logger,
+    title,
+    version,
+    appProps,
+    toolkitOptions,
+    createApp,
+    componentNamespaces: [CoreComponents, SIGIL_COMPONENTS, C],
+  });