@volter/dawproject 0.5.67 → 0.5.68

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/dawproject",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.67",
+  "version": "0.5.68",
   "publishConfig": {
     "access": "public"
   },

package/src/index.ts

@@ -73,6 +73,22 @@ export interface ChannelProps {
   readonly children?: ReactNode;
 }
 
+/**
+ * A modulator on a `<Channel>`, as Bitwig's LFO: a wave added to one of the channel's own
+ * parameters, `target` `volume` or `send:<bus>` (±`depth` dB) or `pan` (±`depth`, the sum
+ * clamped to −1…1). One cycle lasts `period` (a note value or a number of beats, so it follows
+ * the tempo), counted from the piece's first beat and offset by `phase` (0–1 of a cycle). It adds
+ * to the parameter's written value, or to its automation lane where it has one. DAWproject has no
+ * modulators: its export writes the moving parameter as automation points.
+ */
+export interface LfoProps {
+  readonly target: string;
+  readonly shape?: 'sine' | 'triangle' | 'square' | 'saw';
+  readonly period: Length;
+  readonly depth: number;
+  readonly phase?: number;
+}
+
 /** DAWproject `Send`: this channel feeds the `effect` channel of the track named `to`, at `level` dB. */
 export interface SendProps {
   readonly to: string;
@@ -108,9 +124,13 @@ export interface DeviceProps {
   readonly params?: Readonly<Record<string, DeviceParam>>;
 }
 
-/** DAWproject `Clip`: a region of a track's timeline, from bar `at` for `bars` bars. */
+/**
+ * DAWproject `Clip`: a region of a track's timeline, from bar `at` for `bars` bars. In a
+ * `<ClipSlot>` a clip has no `at`: it is a loop of its own, and its notes' positions count from
+ * its start as bar 1.
+ */
 export interface ClipProps {
-  readonly at: Position;
+  readonly at?: Position;
   readonly bars: number;
   readonly name?: string;
   readonly children?: ReactNode;
@@ -131,6 +151,33 @@ export interface NoteProps {
   readonly artic?: 'staccato' | 'staccatissimo' | 'tenuto' | 'accent' | 'marcato' | 'legato' | 'pizzicato' | 'tremolo';
 }
 
+/**
+ * DAWproject `Audio`: a recorded file a `<Clip>` plays, instead of notes. `file` is a WAV at a
+ * project path; it plays from the clip's start (or from `offset` seconds into the file) for the
+ * clip's length, at `gain` dB. A track whose clips hold audio is an audio track: its strip's input
+ * is the files, not an instrument.
+ */
+export interface AudioProps {
+  readonly file: string;
+  readonly offset?: number;
+  readonly gain?: number;
+  /**
+   * The take's name, when a clip holds several recordings of one part (one per pass of a loop):
+   * the newest (last) plays unless `<Comp>`s pick others.
+   */
+  readonly take?: string;
+}
+
+/**
+ * A comp choice in a clip of several takes: from `at` (a position of the piece, inside the clip)
+ * the take named `take` plays, until the next `<Comp>`. Before the first, the newest take plays.
+ * Where the take changes, the two cross in 5 ms.
+ */
+export interface CompProps {
+  readonly take: string;
+  readonly at: Position;
+}
+
 /**
  * DAWproject `Points`: an automation lane. In a `<Clip>`, `target` is a MIDI controller
  * (`cc1` modulation, `cc11` expression, `cc64` sustain, …) or `pitchbend`, with values 0–1
@@ -148,6 +195,22 @@ export interface PointProps {
   readonly hold?: boolean;
 }
 
+/**
+ * DAWproject `Scene`: a row of the clip launcher, a child of `<Project>`. Launching it plays each
+ * of its `<ClipSlot>`s on that slot's track, looping, from the next bar, and stops the tracks it
+ * has no slot for: one scene is one state of the music (a game's explore, combat, calm).
+ */
+export interface SceneProps {
+  readonly name: string;
+  readonly children?: ReactNode;
+}
+
+/** DAWproject `ClipSlot`: the launcher cell of the track named `track` in a scene, holding one `<Clip>`. */
+export interface ClipSlotProps {
+  readonly track: string;
+  readonly children?: ReactNode;
+}
+
 /** DAWproject `Marker`: a named point on the arrangement's timeline. */
 export interface MarkerProps {
   readonly at: Position;
@@ -168,7 +231,12 @@ export const Clip = element<ClipProps>('dawproject.Clip');
 export const Note = element<NoteProps>('dawproject.Note');
 export const Marker = element<MarkerProps>('dawproject.Marker');
 export const Points = element<PointsProps>('dawproject.Points');
+export const Audio = element<AudioProps>('dawproject.Audio');
 export const Point = element<PointProps>('dawproject.Point');
+export const Lfo = element<LfoProps>('dawproject.Lfo');
+export const Comp = element<CompProps>('dawproject.Comp');
+export const Scene = element<SceneProps>('dawproject.Scene');
+export const ClipSlot = element<ClipSlotProps>('dawproject.ClipSlot');
 
 /** Every element this package names, keyed by its short name. */
 export const ELEMENT_TYPES = {
@@ -183,6 +251,11 @@ export const ELEMENT_TYPES = {
   Marker: 'dawproject.Marker',
   Points: 'dawproject.Points',
   Point: 'dawproject.Point',
+  Audio: 'dawproject.Audio',
+  Lfo: 'dawproject.Lfo',
+  Comp: 'dawproject.Comp',
+  Scene: 'dawproject.Scene',
+  ClipSlot: 'dawproject.ClipSlot',
 } as const;
 
 export type ElementName = keyof typeof ELEMENT_TYPES;

package/src/piece.ts

@@ -70,6 +70,29 @@ export interface PieceClip {
   readonly duration: number;
   readonly notes: readonly PieceNote[];
   readonly lanes: readonly PiecePoints[];
+  /** The recorded file this clip plays by default (`<Audio>`, the newest take), or `null` for a note clip. */
+  readonly audio: PieceAudio | null;
+  /** Every `<Audio>` in the clip, oldest first: its takes when there are several. */
+  readonly takes: readonly PieceAudio[];
+  /** Which take plays from where (`<Comp>`), in time order. */
+  readonly comps: readonly PieceComp[];
+}
+
+/** A comp choice: from `time` (beats of the piece) the take named `take` plays. */
+export interface PieceComp {
+  readonly oid: string | null;
+  readonly take: string;
+  readonly time: number;
+}
+
+/** A clip's recorded file: a WAV at a project path, from `offset` seconds into it, at `gain` dB. */
+export interface PieceAudio {
+  readonly oid: string | null;
+  readonly file: string;
+  readonly offset: number;
+  readonly gain: number;
+  /** Its take name (`take`), or its place among the clip's takes from 1 when unnamed. */
+  readonly take: string;
 }
 
 export interface PieceDevice {
@@ -88,6 +111,18 @@ export interface PieceSend {
   readonly pre: boolean;
 }
 
+/** A channel's LFO (`<Lfo>`): a wave added to `target`, one cycle per `period` beats. */
+export interface PieceLfo {
+  readonly oid: string | null;
+  readonly target: string;
+  readonly shape: 'sine' | 'triangle' | 'square' | 'saw';
+  readonly period: number;
+  readonly depth: number;
+  readonly phase: number;
+  /** The period as written (`"h"`, `2`), for an editor field. */
+  readonly writtenPeriod: string;
+}
+
 export interface PieceChannel {
   readonly oid: string | null;
   /** `submix`: a group track's channel, summing the tracks it contains (DAWproject's role). */
@@ -98,6 +133,7 @@ export interface PieceChannel {
   readonly solo: boolean;
   readonly devices: readonly PieceDevice[];
   readonly sends: readonly PieceSend[];
+  readonly lfos: readonly PieceLfo[];
 }
 
 export interface PieceTrack {
@@ -116,6 +152,23 @@ export interface PieceTrack {
   readonly parent: string | null;
 }
 
+/** A launcher cell: the clip the track named `track` loops when the slot is launched. */
+export interface PieceSlot {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly track: string;
+  /** Its clip, whose `time` is 0 and whose notes count from its start; `null` for an empty slot. */
+  readonly clip: PieceClip | null;
+}
+
+/** A row of the clip launcher (`<Scene>`). */
+export interface PieceScene {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly name: string;
+  readonly slots: readonly PieceSlot[];
+}
+
 export interface PieceMarker {
   readonly id: string;
   readonly oid: string | null;
@@ -127,7 +180,9 @@ export interface Piece {
   readonly transport: PieceTransport;
   readonly tracks: readonly PieceTrack[];
   readonly markers: readonly PieceMarker[];
-  /** The last beat any clip reaches. */
+  /** The clip launcher's rows, in source order. */
+  readonly scenes: readonly PieceScene[];
+  /** The last beat any arrangement clip reaches. */
   readonly length: number;
   /** How many nodes each oid rendered; above 1 means the element repeats. */
   readonly oidCounts: ReadonlyMap<string, number>;
@@ -190,7 +245,51 @@ export function readPiece(root: DawNode): Piece {
   const withTempo: PieceTransport = tempoNode ? { ...transport, tempoPoints: readLane(tempoNode, 'transport:tempo', '<Transport>') } : transport;
   const tracks: PieceTrack[] = [];
   const markers: PieceMarker[] = [];
+  const scenes: PieceScene[] = [];
   let length = 0;
+  /**
+   * A clip: on a track, a region from its `at`; in a launcher slot (`arranged` false), a loop of its
+   * own whose time is 0, so its notes' `at` counts from its start as bar 1.
+   */
+  const readClip = (child: DawNode, clipId: string, trackName: string, arranged: boolean): PieceClip => {
+    const clipName = str(child.props['name']);
+    const where = `<Clip${clipName ? ` "${clipName}"` : ''}> on ${trackName}`;
+    const time = arranged ? position(child.props['at'], where) : 0;
+    const duration = num(child.props['bars'], 0) * beatsPerBar;
+    const notes: PieceNote[] = child.children
+      .filter((note) => note.type === 'Note')
+      .map((note, noteIndex) => {
+        const writtenPitch = String(note.props['pitch'] ?? '');
+        const writtenDur = note.props['dur'];
+        const start = position(note.props['at'], `A <Note> in ${where}`);
+        return {
+          id: `${clipId}:note:${noteIndex}`,
+          oid: note.oid,
+          start,
+          time: start - time,
+          duration: beatsOf(typeof writtenDur === 'number' ? writtenDur : String(writtenDur ?? '')),
+          pitch: midiOf(writtenPitch),
+          vel: num(note.props['vel'], 0.7),
+          artic: str(note.props['artic']),
+          written: { at: String(note.props['at'] ?? ''), pitch: writtenPitch, dur: String(writtenDur ?? '') },
+        };
+      });
+    const lanes = child.children.filter((lane) => lane.type === 'Points').map((lane, laneIndex) => readLane(lane, `${clipId}:lane:${laneIndex}`, where));
+    const takes: PieceAudio[] = child.children
+      .filter((part) => part.type === 'Audio')
+      .map((part, takeIndex) => ({
+        oid: part.oid,
+        file: str(part.props['file']) ?? '',
+        offset: num(part.props['offset'], 0),
+        gain: num(part.props['gain'], 0),
+        take: str(part.props['take']) ?? String(takeIndex + 1),
+      }));
+    const comps: PieceComp[] = child.children
+      .filter((part) => part.type === 'Comp')
+      .map((part) => ({ oid: part.oid, take: str(part.props['take']) ?? '', time: position(part.props['at'], `A <Comp> in ${where}`) }))
+      .sort((a, b) => a.time - b.time);
+    return { id: clipId, oid: child.oid, name: clipName, time, duration, notes, lanes, audio: takes.at(-1) ?? null, takes, comps };
+  };
   /**
    * A track, and (after it) every track it contains: a group's children sum into its strip, the
    * group's channel `role="submix"`. `parent` is the group track's id.
@@ -209,6 +308,27 @@ export function readPiece(root: DawNode): Piece {
           sends: child.children
             .filter((send) => send.type === 'Send')
             .map((send) => ({ oid: send.oid, to: str(send.props['to']) ?? '', level: num(send.props['level'], 0), pre: bool(send.props['pre']) })),
+          lfos: child.children
+            .filter((lfo) => lfo.type === 'Lfo')
+            .map((lfo) => {
+              const shape = str(lfo.props['shape']);
+              const period = lfo.props['period'];
+              return {
+                oid: lfo.oid,
+                target: str(lfo.props['target']) ?? '',
+                shape: shape === 'triangle' || shape === 'square' || shape === 'saw' ? shape : 'sine',
+                period: (() => {
+                  try {
+                    return beatsOf(typeof period === 'number' ? period : String(period ?? ''));
+                  } catch (error) {
+                    throw new Error(`The <Lfo> on ${trackName}'s channel has no period it can cycle over: ${error instanceof Error ? error.message : String(error)}`);
+                  }
+                })(),
+                depth: num(lfo.props['depth'], 0),
+                phase: num(lfo.props['phase'], 0),
+                writtenPeriod: String(period ?? ''),
+              };
+            }),
           volume: num(child.props['volume'], 0),
           pan: num(child.props['pan'], 0),
           mute: bool(child.props['mute']),
@@ -224,34 +344,9 @@ export function readPiece(root: DawNode): Piece {
             })),
         };
       } else if (child.type === 'Clip') {
-        const clipId = `${trackId}:clip:${childIndex}`;
-        const clipName = str(child.props['name']);
-        const where = `<Clip${clipName ? ` "${clipName}"` : ''}> on ${trackName}`;
-        const time = position(child.props['at'], where);
-        const duration = num(child.props['bars'], 0) * beatsPerBar;
-        const notes: PieceNote[] = child.children
-          .filter((note) => note.type === 'Note')
-          .map((note, noteIndex) => {
-            const writtenPitch = String(note.props['pitch'] ?? '');
-            const writtenDur = note.props['dur'];
-            const start = position(note.props['at'], `A <Note> in ${where}`);
-            return {
-              id: `${clipId}:note:${noteIndex}`,
-              oid: note.oid,
-              start,
-              time: start - time,
-              duration: beatsOf(typeof writtenDur === 'number' ? writtenDur : String(writtenDur ?? '')),
-              pitch: midiOf(writtenPitch),
-              vel: num(note.props['vel'], 0.7),
-              artic: str(note.props['artic']),
-              written: { at: String(note.props['at'] ?? ''), pitch: writtenPitch, dur: String(writtenDur ?? '') },
-            };
-          });
-        const lanes = child.children
-          .filter((lane) => lane.type === 'Points')
-          .map((lane, laneIndex) => readLane(lane, `${clipId}:lane:${laneIndex}`, where));
-        length = Math.max(length, time + duration);
-        clips.push({ id: clipId, oid: child.oid, name: clipName, time, duration, notes, lanes });
+        const clip = readClip(child, `${trackId}:clip:${childIndex}`, trackName, true);
+        length = Math.max(length, clip.time + clip.duration);
+        clips.push(clip);
       } else if (child.type === 'Points') {
         trackLanes.push(readLane(child, `${trackId}:lane:${childIndex}`, `<Track "${trackName}">`));
       }
@@ -266,9 +361,19 @@ export function readPiece(root: DawNode): Piece {
       markers.push({ id: `marker:${index}`, oid: node.oid, time: position(node.props['at'], 'A <Marker>'), name: str(node.props['name']) ?? '' });
     } else if (node.type === 'Track') {
       readTrack(node, `track:${index}`, null);
+    } else if (node.type === 'Scene') {
+      const sceneId = `scene:${index}`;
+      const slots = node.children.flatMap((slot, slotIndex): PieceSlot[] => {
+        if (slot.type !== 'ClipSlot') return [];
+        const track = str(slot.props['track']) ?? '';
+        const clipNode = slot.children.find((child) => child.type === 'Clip');
+        const id = `${sceneId}:slot:${slotIndex}`;
+        return [{ id, oid: slot.oid, track, clip: clipNode ? readClip(clipNode, `${id}:clip`, track, false) : null }];
+      });
+      scenes.push({ id: sceneId, oid: node.oid, name: str(node.props['name']) ?? `Scene ${scenes.length + 1}`, slots });
     }
   });
-  return { transport: withTempo, tracks, markers, length, oidCounts };
+  return { transport: withTempo, tracks, markers, scenes, length, oidCounts };
 }
 
 /** Seconds per beat at the piece's tempo (a constant tempo; tempo automation is not read yet). */

package/src/render.ts

@@ -16,6 +16,7 @@
 import type { ComponentType, ReactNode } from 'react';
 import { createElement } from 'react';
 import Reconciler from 'react-reconciler';
+import { ELEMENT_TYPES } from './index';
 import { ConcurrentRoot, DefaultEventPriority } from 'react-reconciler/constants.js';
 
 export const OID_PROP = 'data-oid';
@@ -59,7 +60,7 @@ function ownProps(props: Record<string, unknown>): { props: Record<string, unkno
 function shortType(type: string): string {
   if (!type.startsWith(TYPE_PREFIX)) {
     throw new Error(
-      `<${type}> is not a DAWproject element. A piece renders only @volter/dawproject's elements (Project, Transport, Track, Channel, Device, Clip, Note, Marker) and components made of them.`,
+      `<${type}> is not a DAWproject element. A piece renders only @volter/dawproject's elements (${Object.keys(ELEMENT_TYPES).join(', ')}) and components made of them.`,
     );
   }
   return type.slice(TYPE_PREFIX.length);
@@ -163,7 +164,7 @@ const reconciler = Reconciler({
   resolveEventType: () => null,
   resolveEventTimeStamp: () => -1.1,
   rendererPackageName: '@volter/dawproject',
-  rendererVersion: '0.5.67',
+  rendererVersion: '0.5.68',
 } as never);
 
 function snapshot(instance: Instance): DawNode {