@bardway/trpg-media 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lex
+
+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/NOTICE

@@ -0,0 +1,10 @@
+MingriAgency TRPG Engine
+Copyright (c) 2026 Lex
+
+Portions extracted and adapted from MingriAgencyCOC,
+Copyright (c) 2025 Lex, licensed under the MIT License.
+Source: https://github.com/bardway/mingriAgency_COC
+The complete source attribution and extraction mapping are maintained in
+docs/architecture and docs/guidance in the Engine repository.
+
+Third-party dependencies retain their own licenses and copyright notices.

package/NOTICE.md

@@ -0,0 +1 @@
+Source: mingriAgency_COC current local checkout, web/src/features/session-display. Source remains read-only. Product rules, resources, deployments and account data are excluded. Distributed under the repository MIT license. Third-party dependencies retain their own licenses.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @bardway/trpg-media
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+资源重试、预取、Web 音频、视频海报和上传补偿。
+
+初始版本 `0.1.0`，提供 ESM JavaScript 和 TypeScript 声明。
+
+## 安装
+
+```sh
+npm install --save-exact @bardway/trpg-media@0.1.0
+```
+
+按需选择 `/audio`、`/tuning`、`/video`。浏览器能力、资源地址、上传和删除端口由宿主提供。
+
+## 公开入口
+
+- `@bardway/trpg-media`
+- `@bardway/trpg-media/tuning`
+- `@bardway/trpg-media/audio`
+- `@bardway/trpg-media/video`
+
+完整配置、示例和平台限制见[使用说明](https://github.com/bardway/mingriAgency_TRPGEngine/blob/main/docs/guidance/package-usage.md)。
+
+MIT。保留随包分发的 LICENSE、NOTICE 和第三方许可。

package/dist/AudioByteCache.d.ts

@@ -0,0 +1,8 @@
+/** Instance ownership allows a host to share a preload cache without sharing accounts or sessions. */
+export declare class AudioByteCache {
+    private readonly fetchAudio;
+    private readonly records;
+    constructor(fetchAudio?: typeof fetch);
+    load(url: string): Promise<ArrayBuffer>;
+    clear(): void;
+}

package/dist/DisplayAudioController.d.ts

@@ -0,0 +1,2 @@
+export type DisplayAudioState = 'initializing' | 'ready' | 'blocked' | 'failed';
+export declare const classifyDisplayAudioFailure: (error: unknown) => DisplayAudioState;

package/dist/MediaPreloader.d.ts

@@ -0,0 +1,12 @@
+import type { AudioByteCache } from './AudioByteCache.js';
+export interface SessionMediaPreloadResult {
+    readonly failedUrls: readonly string[];
+}
+export declare const preloadSessionAudio: (urls: readonly string[], options: {
+    readonly signal: AbortSignal;
+    readonly onProgress: (completed: number, total: number) => void;
+    readonly concurrency?: number;
+    readonly cache: AudioByteCache;
+    readonly retryCount?: number;
+    readonly retryDelayMs?: number;
+}) => Promise<SessionMediaPreloadResult>;

package/dist/RuntimeLogger.d.ts

@@ -0,0 +1,4 @@
+export interface RuntimeLogger {
+    warn(message: string, context?: unknown): void;
+    error(message: string, context?: unknown): void;
+}

package/dist/audio/HtmlAudioSessionBackend.d.ts

@@ -0,0 +1,36 @@
+import type { SessionAudioBackend } from './SessionAudioBackend.js';
+import type { SessionAudioBus, SessionAudioCueDefinition, SessionAudioCuePlayOptions, SessionAudioEngineState, SessionAudioPlayOptions } from './SessionAudioEngine.js';
+/** Compatibility backend for jsdom and browsers without Web Audio. */
+export declare class HtmlAudioSessionBackend implements SessionAudioBackend {
+    private readonly report;
+    private readonly elements;
+    private readonly activeCueGroups;
+    private readonly playbackOwners;
+    private readonly playbackCleanups;
+    private fieldElement;
+    private masterGain;
+    private readonly busGains;
+    private unlockGeneration;
+    private destroying;
+    private _state;
+    constructor(report?: (error: unknown) => void);
+    get state(): SessionAudioEngineState;
+    unlock(preloadUrls?: string[]): Promise<boolean>;
+    preload(urls: readonly string[]): Promise<void>;
+    play(url: string, options: SessionAudioPlayOptions): Promise<HTMLAudioElement | null>;
+    playCue(cue: SessionAudioCueDefinition, options?: SessionAudioCuePlayOptions): Promise<HTMLAudioElement | null>;
+    stopCueGroup(groupId: string): void;
+    playField(url: string, volume?: number): Promise<void>;
+    replaceField(url: string | null, volume?: number): Promise<void>;
+    suspendField(): void;
+    resumeField(): void;
+    stopField(): void;
+    setMasterGain(value: number): void;
+    setBusGain(bus: SessionAudioBus, value: number): void;
+    setBusMuted(bus: SessionAudioBus, muted: boolean): void;
+    solo(bus: SessionAudioBus | null): void;
+    destroy(): Promise<void>;
+    private reportSafely;
+    private getElement;
+    private releaseCueGroup;
+}

package/dist/audio/SessionAudioBackend.d.ts

@@ -0,0 +1,19 @@
+import type { SessionAudioBus, SessionAudioCueDefinition, SessionAudioCuePlayOptions, SessionAudioEngineState, SessionAudioPlayOptions } from './SessionAudioEngine.js';
+export interface SessionAudioBackend {
+    readonly state: SessionAudioEngineState;
+    unlock(preloadUrls?: string[]): Promise<boolean>;
+    preload(urls: readonly string[]): Promise<void>;
+    play(url: string, options: SessionAudioPlayOptions): Promise<unknown>;
+    playCue(cue: SessionAudioCueDefinition, options?: SessionAudioCuePlayOptions): Promise<unknown>;
+    stopCueGroup(groupId: string): void;
+    playField(url: string, volume?: number): Promise<void>;
+    replaceField(url: string | null, volume?: number): Promise<void>;
+    suspendField(): void;
+    resumeField(): void;
+    stopField(): void;
+    setMasterGain(value: number): void;
+    setBusGain(bus: SessionAudioBus, value: number, rampMs?: number): void;
+    setBusMuted(bus: SessionAudioBus, muted: boolean): void;
+    solo(bus: SessionAudioBus | null): void;
+    destroy(): Promise<void>;
+}

package/dist/audio/SessionAudioEngine.d.ts

@@ -0,0 +1,93 @@
+export type SessionAudioBus = string;
+export type SessionAudioEngineState = 'blocked' | 'initializing' | 'ready' | 'failed';
+export interface SessionAudioCueDefinition {
+    id: string;
+    asset: string;
+    bus: SessionAudioBus;
+    gain: number;
+    polyphony: number;
+    cooldownMs: number;
+    pitchMin?: number;
+    pitchMax?: number;
+    panMin?: number;
+    panMax?: number;
+    loop?: boolean;
+    startOffsetMs?: number;
+    fadeInMs?: number;
+    fadeOutMs?: number;
+    stealMode?: 'oldest' | 'ignoreNewest';
+}
+export interface SessionAudioPlayOptions {
+    signal?: AbortSignal;
+    bus: SessionAudioBus;
+    loop?: boolean;
+    volume?: number;
+    volumeCeiling?: number;
+    playbackRate?: number;
+    pan?: number;
+    startOffsetMs?: number;
+    fadeInMs?: number;
+    fadeOutMs?: number;
+    onEnded?: () => void;
+}
+export interface SessionAudioCuePlayOptions {
+    signal?: AbortSignal;
+    deterministicSeed?: string;
+    onEnded?: () => void;
+    volume?: number;
+    volumeCeiling?: number;
+    playbackRate?: number;
+    pan?: number;
+    voiceGroupId?: string;
+    cooldownId?: string;
+    maxVoices?: number;
+    cooldownMs?: number;
+}
+export declare class SessionAudioEngine {
+    private readonly createContext;
+    private readonly busIds;
+    private readonly limiterBuses;
+    private readonly report;
+    private readonly bytes;
+    private context;
+    private master;
+    private readonly buses;
+    private readonly busGains;
+    private readonly buffers;
+    private readonly activeVoices;
+    private readonly playbackCleanups;
+    private readonly lastCueTimes;
+    private readonly busMute;
+    private soloBus;
+    private masterGain;
+    private fieldSource;
+    private fieldUrl;
+    private fieldRevision;
+    private unlockGeneration;
+    private destroying;
+    private _state;
+    constructor(createContext?: () => AudioContext, fetchAudio?: typeof fetch, busIds?: readonly string[], limiterBuses?: readonly string[], report?: (error: unknown) => void);
+    get state(): SessionAudioEngineState;
+    unlock(preloadUrls?: string[]): Promise<boolean>;
+    preload(urls: readonly string[]): Promise<void>;
+    play(url: string, options: SessionAudioPlayOptions): Promise<AudioBufferSourceNode | null>;
+    playCue(cue: SessionAudioCueDefinition, options?: SessionAudioCuePlayOptions): Promise<AudioBufferSourceNode | null>;
+    playCue(cue: SessionAudioCueDefinition, deterministicSeed?: string, onEnded?: () => void): Promise<AudioBufferSourceNode | null>;
+    stopCueGroup(groupId: string): void;
+    playField(url: string, volume?: number): Promise<void>;
+    replaceField(url: string | null, volume?: number): Promise<void>;
+    suspendField(): void;
+    resumeField(): void;
+    stopField(): void;
+    private stopFieldSource;
+    setMasterGain(value: number): void;
+    setBusGain(bus: SessionAudioBus, value: number, rampMs?: number): void;
+    setBusMuted(bus: SessionAudioBus, muted: boolean): void;
+    solo(bus: SessionAudioBus | null): void;
+    destroy(): Promise<void>;
+    private reportSafely;
+    private ensureGraph;
+    private load;
+    private releaseVoice;
+    private applyBusAudibility;
+}

package/dist/audio/SessionAudioPlaybackPolicy.d.ts

@@ -0,0 +1,8 @@
+export interface SessionAudioPlaybackPolicy {
+    readonly mode: 'production' | 'preview';
+    readonly allowSemanticSideEffects: boolean;
+    readonly allowScrubAudio: boolean;
+    readonly deterministicSeed?: string;
+}
+export declare const productionAudioPlaybackPolicy: SessionAudioPlaybackPolicy;
+export declare const previewAudioPlaybackPolicy: SessionAudioPlaybackPolicy;

package/dist/audio.d.ts

@@ -0,0 +1,5 @@
+export * from './audio/SessionAudioEngine.js';
+export * from './audio/SessionAudioBackend.js';
+export * from './audio/HtmlAudioSessionBackend.js';
+export * from './audio/SessionAudioPlaybackPolicy.js';
+export * from './AudioByteCache.js';