@drop-ai/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 drop.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# @drop-ai/core
+
+drop.ai DAW의 헤드리스 코어 라이브러리. 오디오 편집 도메인 로직, 커맨드 시스템, 오토메이션, 플러그인, MIDI 등 UI 독립적인 모든 기능을 포함한다.
+
+## 왜 분리했는가
+
+기존에는 `src/core/`에 있던 코어 로직이 Next.js 앱과 같은 디렉토리에 섞여 있었다. 문제점:
+
+- **Tone.js 커플링**: `AudioEngine`이 `ToneAudioProvider`를 직접 import하여 브라우저 없이 사용 불가
+- **Zustand 커플링**: `EditorHandler`, `defaultActions`, `dawQueryTool`이 `useDAWStore`를 직접 import
+- **테스트 격리 불가**: Node.js CLI나 headless 환경에서 코어 로직만 테스트하기 어려움
+- **재사용 불가**: 다른 프레임워크(Electron, React Native 등)에서 코어 로직 사용 불가
+
+분리 후:
+
+- `@drop-ai/core`는 **브라우저/프레임워크 의존성 제로**
+- Node.js CLI, 테스트, 다른 프레임워크에서 독립적으로 사용 가능
+- 향후 npm publish 가능
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Next.js App (src/)                                     │
+│  ┌──────────┐ ┌──────────────┐ ┌──────────────────────┐ │
+│  │Components│ │  Stores      │ │  App-level modules   │ │
+│  │(React)   │ │  (Zustand)   │ │  - ToneAudioProvider  │ │
+│  │          │ │  useDAWStore  │ │  - EditorHandler     │ │
+│  │          │ │              │ │  - defaultActions    │ │
+│  │          │ │              │ │  - dawQueryTool      │ │
+│  └────┬─────┘ └──────┬───────┘ └──────────┬───────────┘ │
+│       │              │                     │             │
+│       └──────────────┼─────────────────────┘             │
+│                      │                                   │
+├──────────────────────┼───────────────────────────────────┤
+│                      ▼                                   │
+│  @drop-ai/core (packages/core/)                          │
+│  ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────────┐  │
+│  │Domain  │ │Commands│ │Audio     │ │Automation      │  │
+│  │Session │ │Executor│ │Engine    │ │List, Curve,    │  │
+│  │Track   │ │History │ │Backend(I)│ │Mode            │  │
+│  │Region  │ │55 Impls│ │Exporter  │ └────────────────┘  │
+│  │Playlist│ │15 Hdlrs│ │Meter     │ ┌────────────────┐  │
+│  │Source  │ └────────┘ └──────────┘ │Plugins         │  │
+│  │Range   │ ┌────────┐ ┌──────────┐ │EQ, Reverb,     │  │
+│  │Marker  │ │Lib     │ │Processing│ │Compressor, ... │  │
+│  │MIDI    │ │Signal  │ │Gain, Pan │ └────────────────┘  │
+│  └────────┘ └────────┘ └──────────┘                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 모듈 구조 (193 파일)
+
+### `domain/` — 도메인 모델 (42 파일)
+
+DAW의 핵심 데이터 구조. Ardour의 도메인 모델을 참고하여 설계됨.
+
+| 클래스 | 설명 |
+|--------|------|
+| `Session` | 프로젝트 루트. 트랙, 소스, 마커, 레인지, 템포맵 관리 |
+| `Track` | 오디오/MIDI/Bus/AUX 트랙. Route(IO + 프로세서 체인) 포함 |
+| `Region` | 타임라인 위의 오디오 구간. start, length, sourceStart, fades |
+| `Playlist` | 트랙 내 Region 컬렉션. 레이어, 크로스페이드 지원 |
+| `Source` | 오디오 파일 참조. URL, duration, sampleRate |
+| `Range` | 루프/펀치/선택 범위 (start, end) |
+| `Marker` | 타임라인 마커 (위치 + 이름) |
+| `MidiNote` / `MidiRegion` | MIDI 데이터 |
+| `SendBus` | 센드 버스 (pre/post fader) |
+| `GridSettings` | 그리드 타입, 스냅 모드 |
+| `TempoMap` | BPM 변경 이벤트 관리 |
+| `CrossfadeEngine` | 리전 겹침 시 자동 크로스페이드 계산 |
+| `TransportFSM` | 재생/정지/녹음 상태 머신 |
+| `MixerScene` | 믹서 스냅샷 저장/불러오기 |
+
+모든 도메인 객체는 `Signal` 기반 이벤트를 발행한다:
+```typescript
+session.trackAdded.connect((track: Track) => { ... });
+session.tempoChanged.connect((bpm: number) => { ... });
+track.muteChanged.connect((muted: boolean) => { ... });
+```
+
+### `commands/` — 커맨드 시스템 (62 파일)
+
+Undo/Redo 지원 커맨드 패턴 구현.
+
+- **`CommandExecutor`**: Zod 스키마 검증 → 핸들러 라우팅 → 실행. 싱글톤.
+- **`CommandHistory`**: Undo/Redo 스택 관리. depth 설정 가능.
+- **15개 핸들러**: Transport, Track, Region, Range, Automation, Export, IO, SendBus, Session, Marker, Midi, MixerScene, TrackGroup, History + 앱에서 등록하는 EditorHandler
+- **55개 커맨드 구현체**: AddTrack, MoveRegion, SplitAtPlayhead, SetTrackVolume 등
+
+```typescript
+// 커맨드 실행
+await CommandExecutor.getInstance().execute({
+    type: CommandType.ADD_TRACK,
+    payload: { name: 'Vocals', trackType: 'audio' }
+});
+
+// 앱에서 커스텀 핸들러 등록
+CommandExecutor.getInstance().registerHandler(new EditorHandler());
+```
+
+### `audio/` — 오디오 엔진 (10 파일)
+
+- **`AudioEngine`**: 세션과 백엔드를 연결하는 중앙 컨트롤러. 싱글톤.
+  - 트랜스포트 (play/stop/pause/seek)
+  - 녹음 (audio + MIDI, 펀치, 루프 레코딩)
+  - 미터링 (peak/RMS/LUFS)
+  - 프로세서 체인 동기화
+- **`AudioProvider`**: 인터페이스. 실제 오디오 I/O 추상화.
+  - 앱: `ToneAudioProvider` (Tone.js + Web Audio API)
+  - CLI: `HeadlessAudioProvider`
+  - 테스트: `MockAudioProvider`
+- **`OfflineExporter`**: WAV/MP3/OGG/FLAC 오프라인 렌더링
+- **`PlaylistEngine`**: 샘플 정확도 리전 렌더링 (AudioWorklet용)
+
+```typescript
+// 백엔드 주입 (Dependency Injection)
+const engine = AudioEngine.getInstance(new ToneAudioProvider());
+
+// 또는 headless 환경
+const engine = AudioEngine.getInstance(new HeadlessAudioProvider());
+```
+
+### `automation/` — 오토메이션 (6 파일)
+
+| 클래스 | 설명 |
+|--------|------|
+| `AutomationList` | 파라미터별 오토메이션 포인트 컬렉션 |
+| `AutomationCurve` | 보간 (linear, exponential, s-curve) |
+| `AutomationMode` | Read, Write, Touch, Latch |
+| `PointThinning` | 실시간 녹음 시 포인트 간소화 |
+| `ParameterDescriptor` | 파라미터 메타데이터 (min, max, default) |
+
+### `plugins/` — 플러그인 시스템 (16 파일)
+
+내장 오디오 플러그인:
+
+| 플러그인 | 설명 |
+|----------|------|
+| `ParametricEQPlugin` | 6밴드 파라메트릭 EQ |
+| `MultibandCompressorPlugin` | 멀티밴드 컴프레서 |
+| `ConvolutionReverbPlugin` | 컨볼루션 리버브 |
+| `SyncDelayPlugin` | BPM 동기 딜레이 |
+| `TapeSaturationPlugin` | 테이프 새추레이션 |
+| `DeEsserPlugin` | 디에서 |
+| `ExpanderPlugin` | 익스팬더/게이트 |
+| `PhaserPlugin` | 페이저 |
+| `TremoloPlugin` | 트레몰로 |
+| `VibratoPlugin` | 비브라토 |
+| `AutoPanPlugin` | 오토 팬 |
+
+`PluginManager`로 등록/생성:
+```typescript
+const manager = PluginManager.getInstance();
+const eq = manager.createPlugin('internal-parametric-eq');
+```
+
+### `processing/` — 신호 처리 체인 (8 파일)
+
+Route(트랙 당 프로세서 체인)를 구성하는 프로세서들:
+
+- `GainProcessor` (Fader / Trim)
+- `PanProcessor` (스테레오 패닝 + 폭 조절)
+- `PolarityProcessor` (위상 반전)
+- `SendProcessor` (Pre/Post fader 센드)
+- `MeterProcessor` (피크/RMS 미터링)
+- `PluginInsert` (플러그인 삽입 슬롯)
+
+### `lib/` — 유틸리티
+
+- **`Signal<T>`**: 타입 안전 이벤트 시스템. Qt의 Signal/Slot 패턴.
+
+```typescript
+const signal = new Signal<number>();
+const sub = signal.connect((value) => console.log(value));
+signal.emit(42);
+sub.dispose(); // 구독 해제
+```
+
+### `actions/` — 액션 레지스트리 (2 파일)
+
+키보드 단축키 ↔ 커맨드 매핑 시스템.
+
+- `ActionRegistry`: 액션 등록/조회/실행
+- `ActionDefinition`: id, label, category, defaultKey, commandFactory
+
+```typescript
+const registry = ActionRegistry.getInstance();
+registry.registerDefaults(defaultActions); // 앱에서 등록
+await registry.execute('transport.togglePlay');
+```
+
+### `preferences/` — 설정 (3 파일)
+
+- `Preferences`: 싱글톤. audioBufferSize, sampleRate, theme, gridSubdivision 등
+- `KeyBindings`: 커스텀 키 바인딩 오버라이드
+
+### `storage/` — 세션 저장 (3 파일)
+
+- `SessionStorage`: IndexedDB/localStorage 기반 세션 저장/불러오기
+- `AutoSave`: 주기적 자동 저장
+- `SessionTemplate`: 새 세션 템플릿
+
+### `ai/` — AI 에이전트 (5 파일)
+
+- `DAWAgent`: LLM 기반 DAW 제어 에이전트
+- `dawCommandTool`: AI가 커맨드를 실행하는 도구
+- `dawSystemPrompt`: DAW 컨텍스트 시스템 프롬프트
+
+## 앱에서의 사용법
+
+### 부트스트랩 (useDAWStore.init)
+
+```typescript
+import { AudioEngine } from '@drop-ai/core/audio/AudioEngine';
+import { CommandExecutor } from '@drop-ai/core/commands/CommandExecutor';
+import { ActionRegistry } from '@drop-ai/core/actions/ActionRegistry';
+import { ToneAudioProvider } from '../audio/ToneAudioProvider';
+import { EditorHandler } from '../app-commands/EditorHandler';
+import { defaultActions } from '../app-actions/defaultActions';
+
+// 1. 오디오 백엔드 주입
+AudioEngine.getInstance(new ToneAudioProvider());
+
+// 2. 앱 전용 커맨드 핸들러 등록
+CommandExecutor.getInstance().registerHandler(new EditorHandler());
+
+// 3. 기본 액션(키보드 단축키) 등록
+ActionRegistry.getInstance().registerDefaults(defaultActions);
+```
+
+### Import 패턴
+
+```typescript
+// barrel import (주요 타입)
+import { Session, Track, Region, AudioEngine } from '@drop-ai/core';
+
+// deep import (특정 모듈)
+import { AudioEngine } from '@drop-ai/core/audio/AudioEngine';
+import { CommandType } from '@drop-ai/core/commands/types';
+import { Signal } from '@drop-ai/core/lib/Signal';
+import { TempoMap } from '@drop-ai/core/domain/temporal/TempoMap';
+```
+
+## 앱 쪽에 남긴 파일 (7개)
+
+브라우저/스토어 의존성 때문에 코어에 포함할 수 없는 파일들:
+
+| 파일 | 위치 | 이유 |
+|------|------|------|
+| `ToneAudioProvider.ts` | `src/audio/` | Tone.js + browser AudioContext |
+| `ToneTrack.ts` | `src/audio/` | Tone.js import |
+| `TrackProcessor.ts` | `src/audio/worklets/` | AudioWorklet browser API |
+| `TimeStretchProcessor.ts` | `src/audio/` | soundtouchjs + OfflineAudioContext |
+| `defaultActions.ts` | `src/app-actions/` | useDAWStore import |
+| `EditorHandler.ts` | `src/app-commands/` | useDAWStore import |
+| `dawQueryTool.ts` | `src/app-ai/` | useDAWStore import |
+
+## 디커플링 요약
+
+| 변경 | Before | After |
+|------|--------|-------|
+| `AudioEngine` | `ToneAudioProvider` 하드코딩 | 백엔드 주입 필수 (DI) |
+| `CommandExecutor` | `EditorHandler` 내장 | `registerHandler()` API |
+| `ActionRegistry` | `defaultActions` 자동 로드 | `registerDefaults()` API |
+| `KeyBindings` / `Preferences` | `localStorage` 직접 접근 | `typeof localStorage` 가드 |
+| `ExportHandler` | `document.createElement` 직접 호출 | `typeof document` 가드 |
+| `ai/tools` | `dawQueryTool` 내장 | 앱에서 별도 관리 |
+
+## 설정 파일
+
+### pnpm-workspace.yaml
+```yaml
+packages:
+  - "packages/*"
+```
+
+### 루트 package.json (의존성)
+```json
+{
+  "dependencies": {
+    "@drop-ai/core": "workspace:*"
+  }
+}
+```
+
+### 루트 tsconfig.json (paths)
+```json
+{
+  "paths": {
+    "@/*": ["./*"],
+    "@drop-ai/core": ["./packages/core/src"],
+    "@drop-ai/core/*": ["./packages/core/src/*"]
+  }
+}
+```
+
+## 테스트
+
+```bash
+# 전체 단위 테스트 (308개)
+pnpm test
+
+# 코어 패키지 타입 체크
+cd packages/core && npx tsc --noEmit
+
+# 루트 프로젝트 타입 체크
+npx tsc --noEmit
+```
+
+## 향후 계획
+
+- [ ] `packages/core/` 빌드 파이프라인 (`tsc` → `dist/`)
+- [ ] npm publish (`private: false`)
+- [ ] Electron 앱에서 `@drop-ai/core` 재사용
+- [ ] 코어 전용 단위 테스트 (`packages/core/test/`)

package/dist/actions/ActionRegistry.d.ts

@@ -0,0 +1,33 @@
+import { ActionDefinition, ActionId } from './types';
+export declare class ActionRegistry {
+    private static instance;
+    private actions;
+    private keyMap;
+    private constructor();
+    static getInstance(): ActionRegistry;
+    registerDefaults(actions: ActionDefinition[]): void;
+    register(action: ActionDefinition): void;
+    getAction(id: ActionId): ActionDefinition | undefined;
+    getAllActions(): ActionDefinition[];
+    /**
+     * Resolve the effective key for an action, checking custom bindings first,
+     * then falling back to the default key.
+     */
+    getEffectiveKey(actionId: ActionId): string | undefined;
+    /**
+     * Look up an action by key string, checking custom bindings first,
+     * then falling back to default key map.
+     */
+    getActionIdByKey(key: string): ActionId | undefined;
+    /**
+     * Rebuild the key map (useful after registering new actions or changing bindings).
+     */
+    rebuildKeyMap(): void;
+    /**
+     * Get all actions grouped by category.
+     * Category is derived from action ID prefix (e.g., "transport.play" -> "Transport").
+     */
+    getActionsByCategory(): Map<string, ActionDefinition[]>;
+    execute(id: ActionId, context?: Record<string, unknown>): Promise<void>;
+}
+//# sourceMappingURL=ActionRegistry.d.ts.map

package/dist/actions/ActionRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionRegistry.d.ts","sourceRoot":"","sources":["../../src/actions/ActionRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIrD,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IACxC,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,MAAM,CAAoC;IAElD,OAAO;WAEO,WAAW,IAAI,cAAc;IAOpC,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAMnD,QAAQ,CAAC,MAAM,EAAE,gBAAgB;IAOjC,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,gBAAgB,GAAG,SAAS;IAIrD,aAAa,IAAI,gBAAgB,EAAE;IAI1C;;;OAGG;IACI,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS;IAQ9D;;;OAGG;IACI,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAc1D;;OAEG;IACI,aAAa,IAAI,IAAI;IAS5B;;;OAGG;IACI,oBAAoB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAiBjD,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAUvF"}

package/dist/actions/ActionRegistry.js

@@ -0,0 +1,96 @@
+import { CommandExecutor } from '../commands/CommandExecutor';
+import { KeyBindings } from '../preferences/KeyBindings';
+export class ActionRegistry {
+    constructor() {
+        this.actions = new Map();
+        this.keyMap = new Map();
+    }
+    static getInstance() {
+        if (!ActionRegistry.instance) {
+            ActionRegistry.instance = new ActionRegistry();
+        }
+        return ActionRegistry.instance;
+    }
+    registerDefaults(actions) {
+        actions.forEach((action) => {
+            this.register(action);
+        });
+    }
+    register(action) {
+        this.actions.set(action.id, action);
+        if (action.defaultKey) {
+            this.keyMap.set(action.defaultKey.toLowerCase(), action.id);
+        }
+    }
+    getAction(id) {
+        return this.actions.get(id);
+    }
+    getAllActions() {
+        return Array.from(this.actions.values());
+    }
+    /**
+     * Resolve the effective key for an action, checking custom bindings first,
+     * then falling back to the default key.
+     */
+    getEffectiveKey(actionId) {
+        var _a;
+        const customBinding = KeyBindings.getInstance().getBinding(actionId);
+        if (customBinding !== undefined) {
+            return customBinding;
+        }
+        return (_a = this.actions.get(actionId)) === null || _a === void 0 ? void 0 : _a.defaultKey;
+    }
+    /**
+     * Look up an action by key string, checking custom bindings first,
+     * then falling back to default key map.
+     */
+    getActionIdByKey(key) {
+        const lowerKey = key.toLowerCase();
+        // Check custom bindings first (they take priority)
+        const customBindings = KeyBindings.getInstance().getAllBindings();
+        for (const [actionId, keyCombo] of customBindings) {
+            if (keyCombo.toLowerCase() === lowerKey) {
+                return actionId;
+            }
+        }
+        return this.keyMap.get(lowerKey);
+    }
+    /**
+     * Rebuild the key map (useful after registering new actions or changing bindings).
+     */
+    rebuildKeyMap() {
+        this.keyMap.clear();
+        for (const action of this.actions.values()) {
+            if (action.defaultKey) {
+                this.keyMap.set(action.defaultKey.toLowerCase(), action.id);
+            }
+        }
+    }
+    /**
+     * Get all actions grouped by category.
+     * Category is derived from action ID prefix (e.g., "transport.play" -> "Transport").
+     */
+    getActionsByCategory() {
+        const categories = new Map();
+        for (const action of this.actions.values()) {
+            const dotIndex = action.id.indexOf('.');
+            const categoryKey = dotIndex >= 0 ? action.id.substring(0, dotIndex) : 'general';
+            const categoryLabel = categoryKey.charAt(0).toUpperCase() + categoryKey.slice(1);
+            if (!categories.has(categoryLabel)) {
+                categories.set(categoryLabel, []);
+            }
+            categories.get(categoryLabel).push(action);
+        }
+        return categories;
+    }
+    async execute(id, context) {
+        const action = this.actions.get(id);
+        if (!action) {
+            console.warn(`Action not found: ${id}`);
+            return;
+        }
+        const command = action.commandFactory(context);
+        await CommandExecutor.getInstance().execute(command);
+    }
+}
+//# sourceMappingURL=ActionRegistry.js.map

package/dist/actions/ActionRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionRegistry.js","sourceRoot":"","sources":["../../src/actions/ActionRegistry.ts"],"names":[],"mappings":"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"}

package/dist/actions/types.d.ts

@@ -0,0 +1,31 @@
+import { AudioCommand } from '../commands/types';
+export type ActionId = string;
+export declare enum ActionCategory {
+    TRANSPORT = "Transport",
+    TRACK = "Track",
+    REGION = "Region",
+    EDIT = "Edit",
+    VIEW = "View",
+    FILE = "File",
+    DEBUG = "Debug"
+}
+export interface ActionDefinition {
+    id: ActionId;
+    label: string;
+    category: ActionCategory;
+    description?: string;
+    /**
+     * Factory function to create the command payload.
+     * Can accept context arguments if needed.
+     */
+    commandFactory: (context?: Record<string, unknown>) => AudioCommand;
+    /**
+     * Default key binding (e.g. 'Space', 'Control+Z')
+     */
+    defaultKey?: string;
+}
+export interface KeyBinding {
+    actionId: ActionId;
+    key: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/actions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/actions/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,oBAAY,cAAc;IACtB,SAAS,cAAc;IACvB,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,QAAQ,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,YAAY,CAAC;IACpE;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACf"}

package/dist/actions/types.js

@@ -0,0 +1,11 @@
+export var ActionCategory;
+(function (ActionCategory) {
+    ActionCategory["TRANSPORT"] = "Transport";
+    ActionCategory["TRACK"] = "Track";
+    ActionCategory["REGION"] = "Region";
+    ActionCategory["EDIT"] = "Edit";
+    ActionCategory["VIEW"] = "View";
+    ActionCategory["FILE"] = "File";
+    ActionCategory["DEBUG"] = "Debug";
+})(ActionCategory || (ActionCategory = {}));
+//# sourceMappingURL=types.js.map

package/dist/actions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/actions/types.ts"],"names":[],"mappings":"AAIA,MAAM,CAAN,IAAY,cAQX;AARD,WAAY,cAAc;IACtB,yCAAuB,CAAA;IACvB,iCAAe,CAAA;IACf,mCAAiB,CAAA;IACjB,+BAAa,CAAA;IACb,+BAAa,CAAA;IACb,+BAAa,CAAA;IACb,iCAAe,CAAA;AACnB,CAAC,EARW,cAAc,KAAd,cAAc,QAQzB"}

package/dist/analysis/TransientDetector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TransientDetector — spectral-flux based onset / transient detection.
+ *
+ * Uses a windowed FFT approach with spectral flux to identify percussive
+ * onsets and transient events in audio data.  The algorithm:
+ *
+ *   1. Slide a Hann window across the signal (window size 1024, hop 512).
+ *   2. Compute the magnitude spectrum via a real-valued DFT.
+ *   3. For each frame, compute spectral flux — the sum of positive
+ *      differences between the current and previous magnitude spectrum.
+ *   4. Peak-pick: choose frames whose spectral flux exceeds a local
+ *      threshold (median of a surrounding window, scaled by a sensitivity
+ *      parameter).
+ *
+ * This is intentionally a pure-TypeScript implementation that runs without
+ * Web Audio API so it can be used in headless / test environments.
+ */
+/**
+ * Detect transient positions in a mono audio buffer.
+ *
+ * @param samples     Mono audio samples (Float32Array).
+ * @param sampleRate  Sample rate of the audio (used only for documentation;
+ *                    results are returned in sample frames).
+ * @param threshold   Sensitivity multiplier (lower = more onsets). Default 1.5.
+ * @returns           Sorted array of frame positions where transients occur.
+ */
+export declare function detectTransients(samples: Float32Array, sampleRate: number, threshold?: number): number[];
+//# sourceMappingURL=TransientDetector.d.ts.map

package/dist/analysis/TransientDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransientDetector.d.ts","sourceRoot":"","sources":["../../src/analysis/TransientDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC5B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAA0B,GACtC,MAAM,EAAE,CAmEV"}

package/dist/analysis/TransientDetector.js

@@ -0,0 +1,109 @@
+/**
+ * TransientDetector — spectral-flux based onset / transient detection.
+ *
+ * Uses a windowed FFT approach with spectral flux to identify percussive
+ * onsets and transient events in audio data.  The algorithm:
+ *
+ *   1. Slide a Hann window across the signal (window size 1024, hop 512).
+ *   2. Compute the magnitude spectrum via a real-valued DFT.
+ *   3. For each frame, compute spectral flux — the sum of positive
+ *      differences between the current and previous magnitude spectrum.
+ *   4. Peak-pick: choose frames whose spectral flux exceeds a local
+ *      threshold (median of a surrounding window, scaled by a sensitivity
+ *      parameter).
+ *
+ * This is intentionally a pure-TypeScript implementation that runs without
+ * Web Audio API so it can be used in headless / test environments.
+ */
+const DEFAULT_WINDOW_SIZE = 1024;
+const DEFAULT_HOP_SIZE = 512;
+const DEFAULT_THRESHOLD = 1.5;
+const MEDIAN_WINDOW = 11; // frames around current for adaptive threshold
+/**
+ * Detect transient positions in a mono audio buffer.
+ *
+ * @param samples     Mono audio samples (Float32Array).
+ * @param sampleRate  Sample rate of the audio (used only for documentation;
+ *                    results are returned in sample frames).
+ * @param threshold   Sensitivity multiplier (lower = more onsets). Default 1.5.
+ * @returns           Sorted array of frame positions where transients occur.
+ */
+export function detectTransients(samples, sampleRate, threshold = DEFAULT_THRESHOLD) {
+    const windowSize = DEFAULT_WINDOW_SIZE;
+    const hopSize = DEFAULT_HOP_SIZE;
+    const halfWindow = windowSize >>> 1;
+    if (samples.length < windowSize) {
+        return [];
+    }
+    // Pre-compute Hann window
+    const hann = new Float32Array(windowSize);
+    for (let i = 0; i < windowSize; i++) {
+        hann[i] = 0.5 * (1 - Math.cos((2 * Math.PI * i) / (windowSize - 1)));
+    }
+    const numFrames = Math.floor((samples.length - windowSize) / hopSize) + 1;
+    const fluxValues = new Array(numFrames);
+    let prevMagnitudes = new Array(halfWindow + 1).fill(0);
+    for (let frame = 0; frame < numFrames; frame++) {
+        const offset = frame * hopSize;
+        // Apply Hann window
+        const windowed = new Float32Array(windowSize);
+        for (let i = 0; i < windowSize; i++) {
+            windowed[i] = samples[offset + i] * hann[i];
+        }
+        // Compute magnitude spectrum via real DFT (only positive frequencies)
+        const magnitudes = realDFTMagnitudes(windowed, halfWindow);
+        // Spectral flux: sum of positive differences
+        let flux = 0;
+        for (let k = 0; k <= halfWindow; k++) {
+            const diff = magnitudes[k] - prevMagnitudes[k];
+            if (diff > 0) {
+                flux += diff;
+            }
+        }
+        fluxValues[frame] = flux;
+        prevMagnitudes = magnitudes;
+    }
+    // Adaptive peak picking using a median-based threshold
+    const transients = [];
+    const halfMedian = (MEDIAN_WINDOW - 1) >>> 1;
+    for (let frame = 0; frame < numFrames; frame++) {
+        // Gather surrounding flux values for median computation
+        const start = Math.max(0, frame - halfMedian);
+        const end = Math.min(numFrames - 1, frame + halfMedian);
+        const neighbourhood = [];
+        for (let j = start; j <= end; j++) {
+            neighbourhood.push(fluxValues[j]);
+        }
+        neighbourhood.sort((a, b) => a - b);
+        const median = neighbourhood[neighbourhood.length >>> 1];
+        if (fluxValues[frame] > median * threshold && fluxValues[frame] > 0) {
+            // Convert frame index to sample position (center of hop)
+            const samplePos = frame * hopSize + (halfWindow);
+            transients.push(samplePos);
+        }
+    }
+    return transients;
+}
+/**
+ * Compute magnitude spectrum for real-valued input via a naive DFT.
+ *
+ * Only computes bins 0..N/2 (positive frequencies).  This is O(N * N/2)
+ * which is acceptable for small window sizes (1024).
+ */
+function realDFTMagnitudes(input, halfN) {
+    const N = input.length;
+    const mags = new Array(halfN + 1);
+    for (let k = 0; k <= halfN; k++) {
+        let re = 0;
+        let im = 0;
+        const freqFactor = (2 * Math.PI * k) / N;
+        for (let n = 0; n < N; n++) {
+            const angle = freqFactor * n;
+            re += input[n] * Math.cos(angle);
+            im -= input[n] * Math.sin(angle);
+        }
+        mags[k] = Math.sqrt(re * re + im * im);
+    }
+    return mags;
+}
+//# sourceMappingURL=TransientDetector.js.map