@panelwave/player 1.5.0 → 1.6.1

package/index.d.ts

@@ -1433,8 +1433,14 @@ interface SequenceAudioTrack {
     muted?: boolean;
     /** Optional explicit panel range start */
     startPanelId?: string;
-    /** Optional explicit panel range end */
+    /** Optional explicit panel range end (span 'work': may be in a later chapter) */
     endPanelId?: string;
+    /**
+     * How long the track lasts, as authored (format 1.8.0, additive; default
+     * 'custom'): 'page' / 'chapter' = that panel range, 'work' = keeps playing
+     * across chapter boundaries until endPanelId (else the last panel).
+     */
+    span?: 'custom' | 'page' | 'chapter' | 'work';
 }
 /**
  * Chapter containing panels and navigation graph
@@ -3232,6 +3238,8 @@ interface AudioTrack {
     volume?: number;
     fadeIn?: number;
     fadeOut?: number;
+    /** Playback speed (0.25-4; 1 = as recorded). */
+    playbackRate?: number;
 }
 /**
  * Playback state
@@ -3304,9 +3312,9 @@ declare class AudioEngineService {
      */
     resumeContext(): Promise<void>;
     /**
-     * Play audio track
+     * Play audio track, optionally from `offsetSeconds` into the file.
      */
-    play(track: AudioTrack): Promise<void>;
+    play(track: AudioTrack, offsetSeconds?: number): Promise<void>;
     /**
      * Stop audio track
      */
@@ -3421,6 +3429,119 @@ declare class AudioEngineService {
     static ɵprov: i0.ɵɵInjectableDeclaration<AudioEngineService>;
 }
 
+/**
+ * Sequence Audio Service
+ *
+ * Plays a work's timeline audio (`chapters[].sequenceAudioTracks` — music,
+ * ambience, voiceover beds) while the reader moves through the panels:
+ *
+ * - entering a panel starts every track that covers it, at the right offset
+ *   (a jump into the middle of a scene picks the music up where it is);
+ * - a track keeps playing while the reader stays inside its range, so
+ *   music does not restart on every panel; leaving the range fades it out
+ *   (its `fadeOut`, else 250 ms);
+ * - a track that starts or ends inside a panel is delayed / stopped there;
+ * - `span: 'work'` tracks continue across chapter boundaries.
+ *
+ * Placement follows the CMS timeline (see sequence-audio-timeline.ts). Roles
+ * map onto the engine buses, so the reader's Audio / SFX / Speech toggles
+ * apply. Tracks refused by the autoplay policy are retried on the first
+ * user gesture.
+ */
+
+/** Fade when a track ends because the reader left its range (unless it has its own fadeOut). */
+declare const SEQUENCE_AUDIO_LEAVE_FADE_MS = 250;
+declare class SequenceAudioService implements OnDestroy {
+    private readonly engine;
+    private readonly manifestService;
+    private readonly gesture;
+    /** Tracks the current panel wants, by engine id. */
+    private desired;
+    /** Refused by the autoplay policy; retried on the first gesture. */
+    private blocked;
+    private warned;
+    private layoutCache?;
+    private readonly gestureSub;
+    constructor();
+    ngOnDestroy(): void;
+    /**
+     * Follow the reader: call on every panel change (and when the page format
+     * changes). `panelId` undefined = silence (cover, locked panel, teardown).
+     */
+    syncPanel(panelId: string | undefined, format: string | null): void;
+    /** Stop everything this service started. */
+    stopAll(): void;
+    /** Engine ids of the tracks the current panel wants (started, pending or blocked). */
+    getDesiredTrackIds(): string[];
+    private layout;
+    private schedule;
+    /** Stop the track inside this panel when its range ends here. */
+    private armStop;
+    private start;
+    private release;
+    private leaveFade;
+    private onUserGesture;
+    private isAutoplayRefusal;
+    private warnOnce;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SequenceAudioService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SequenceAudioService>;
+}
+
+/**
+ * Timeline (sequence) audio placement for the reader — the same model as the
+ * CMS editor's timeline: the work is one line of panels (chapters in order →
+ * the active format's pages → reading order), each panel lasting its
+ * `durationMs` (else the work's seconds-per-panel, else 5 s).
+ *
+ * A chapter's `sequenceAudioTracks` sit on that line relative to their
+ * chapter's start. `span` (format 1.8.0): 'page' / 'chapter' tracks cover
+ * their startPanelId..endPanelId range; a 'work' track keeps playing across
+ * chapter boundaries until endPanelId (else the work's last panel); every
+ * other track ends with its chapter.
+ *
+ * The reader does not follow a clock, so the timeline is used per panel:
+ * entering a panel tells which tracks cover it, from which offset, and
+ * whether one starts or ends inside it (`cuesForPanel`).
+ */
+
+interface TimelineEntry {
+    panelId: string;
+    chapterId: string;
+    startMs: number;
+    endMs: number;
+}
+interface WorkTimeline {
+    entries: TimelineEntry[];
+    byPanel: Map<string, TimelineEntry>;
+    chapters: Map<string, {
+        startMs: number;
+        endMs: number;
+    }>;
+    endMs: number;
+}
+interface TrackRange {
+    track: SequenceAudioTrack;
+    chapterId: string;
+    startMs: number;
+    endMs: number;
+}
+/** What to do with a track when the reader enters a panel. */
+interface PanelCue {
+    range: TrackRange;
+    /** The track starts this long after the panel is entered (0 = at once). */
+    delayMs: number;
+    /** Timeline position inside the track when it starts (ms). */
+    offsetMs: number;
+    /** The track ends inside this panel, this long after entering it. */
+    stopAfterMs?: number;
+}
+/** The work's panel line for a page format (null = every page). */
+declare function buildWorkTimeline(manifest: PanelWaveManifest | null | undefined, format: string | null, defaultPanelMs?: number): WorkTimeline;
+/** Where each (format-matching, unmuted) timeline track sits on the work line. */
+declare function resolveTrackRanges(manifest: PanelWaveManifest | null | undefined, timeline: WorkTimeline, format: string | null): TrackRange[];
+/** The tracks that sound while the reader is on `entry`'s panel. */
+declare function cuesForPanel(ranges: readonly TrackRange[], entry: TimelineEntry): PanelCue[];
+
 /**
  * Panel Audio Service
  *
@@ -3497,12 +3618,6 @@ declare class PanelAudioService implements OnDestroy {
     private isAutoplayRefusal;
     private resolve;
     private resolveTrack;
-    /**
-     * First variant the browser reports it can play; otherwise the first one
-     * (the element will surface the real error).
-     */
-    private pickVariant;
-    private createProbe;
     private clampGain;
     private warnOnce;
     static ɵfac: i0.ɵɵFactoryDeclaration<PanelAudioService, never>;
@@ -6614,6 +6729,7 @@ declare class PlayerShellComponent implements OnInit, OnChanges, AfterViewChecke
     private readonly cdr;
     private readonly audioEngine;
     private readonly panelAudio;
+    private readonly sequenceAudio;
     /**
      * Reading order per panel id (1-based, across chapters), computed once per
      * manifest. Reported as `panelOrder` on panel_view / funnel events and as
@@ -7547,6 +7663,14 @@ declare class SpeechBubblesComponent implements OnChanges, AfterViewInit, OnDest
      * screens (phones) get smaller lettering.
      */
     readingScale: number;
+    /**
+     * Page view: place a tailed balloon by its AUTHORED tail tip (the speaker
+     * on the artwork) instead of centring its body on the stored box, and keep
+     * the tail at its authored length when the MIN_LETTERING_PX floor boosts
+     * the balloon — the CMS editor's page view rule (PanelRenderer), which the
+     * lettered PDF must reproduce. Panel view keeps the centre placement.
+     */
+    anchorTailTip: boolean;
     /**
      * Work-level balloon config defaults (from settings.typography.balloon_config)
      */
@@ -7617,7 +7741,7 @@ declare class SpeechBubblesComponent implements OnChanges, AfterViewInit, OnDest
      */
     onBubbleClick(bubble: SpeechBubble, event: MouseEvent): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SpeechBubblesComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SpeechBubblesComponent, "pw-speech-bubbles", never, { "bubbles": { "alias": "bubbles"; "required": false; }; "locale": { "alias": "locale"; "required": false; }; "containerWidth": { "alias": "containerWidth"; "required": false; }; "containerHeight": { "alias": "containerHeight"; "required": false; }; "readingScale": { "alias": "readingScale"; "required": false; }; "workBalloonConfig": { "alias": "workBalloonConfig"; "required": false; }; "characters": { "alias": "characters"; "required": false; }; }, { "bubbleClick": "bubbleClick"; "bubbleAudioPlay": "bubbleAudioPlay"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpeechBubblesComponent, "pw-speech-bubbles", never, { "bubbles": { "alias": "bubbles"; "required": false; }; "locale": { "alias": "locale"; "required": false; }; "containerWidth": { "alias": "containerWidth"; "required": false; }; "containerHeight": { "alias": "containerHeight"; "required": false; }; "readingScale": { "alias": "readingScale"; "required": false; }; "anchorTailTip": { "alias": "anchorTailTip"; "required": false; }; "workBalloonConfig": { "alias": "workBalloonConfig"; "required": false; }; "characters": { "alias": "characters"; "required": false; }; }, { "bubbleClick": "bubbleClick"; "bubbleAudioPlay": "bubbleAudioPlay"; }, never, never, true, never>;
 }
 
 /**
@@ -8133,5 +8257,5 @@ declare class PlayerComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<PlayerComponent, "pw-player", never, {}, {}, never, never, true, never>;
 }
 
-export { ANONYMOUS_READER, ActionModalComponent, AgeGateComponent, AssetUrlService, AudioEngineService, BranchChooserComponent, CANVAS_PANEL_BUDGET, CanvasCameraService, CanvasStageComponent, ComicBalloon, DEFAULT_BALLOON_CONFIG, DEFAULT_PAGE_BACKGROUND, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_VIDEO_MUTED, DEFAULT_VIDEO_PLAY_MODE, DEFAULT_VIDEO_START_MODE, EntitlementError, EntitlementService, ExportService, FlowEngineService, HotspotActionService, HotspotsOverlayComponent, HttpEntitlementAdapter, ImageCacheService, LOCATION_PARAMS, ManifestService, MockEntitlementAdapter, NullEntitlementAdapter, PANEL_AUDIO_LEAVE_FADE_MS, PanelAudioService, PaywallOverlayComponent, PaywallService, PlayerComponent, PlayerEvent, PlayerService, PlayerShellComponent, PlayerStateService, PluginHostService, PluginSandboxComponent, PreloadService, PwIconComponent, RESERVED_NAMESPACES, SpeechBubblesComponent, THUMBNAIL_WIDTH, TrackingService, TranslationService, UserGestureService, VISIBILITY_THRESHOLD, VariableStoreService, VideoControllerService, VideoLayerComponent, VideoSequencerService, VisibilityService, applyVariantOverrides, balloonConfigToRenderOptions, balloonConfigToTailOptions, busForRole, chapterOrderFromManifest, coverImageSrc, createBalloon, evaluatePanelAccess, evaluateWorkAccess, findWorkGateRule, fromManifestRule, isExtraLocked, isLockedPanel, locationUrl, mergeBalloonConfig, pageAspectRatio, pageFormatOf, pageFormatsOf, pagesForFormat, panelThumbnailSrc, parseLocationSearch, pickPageFormat, rankPageFormats, readingOrderFromManifest, resolveMuted, resolvePageBackground, resolvePanelVariant, resolvePanels, resolvePlayMode, resolveStartMode, resolveVideoConfig, rulesFromManifest, satisfiesRule, screenClassFor, selectVariant, toEntitlementStatus };
-export type { AccessDecision, AgeVerificationResult, AnimatableProperty, AnimationEasing, AnimationKeyframe, AssetBase, AssetCatalogItem, AssetCatalogItemAudio, AssetCatalogItemImage, AssetCatalogItemJson, AssetCatalogItemPluginPayload, AssetCatalogItemSubtitle, AssetCatalogItemVector, AssetCatalogItemVideo, AssetCategory, AssetCommon, AssetRef, AssetReference, AssetVariant, Assets, AudioLayer, AudioRole, AudioTrack, AudioVariant, BalloonConfig, BalloonConfigOverride, BalloonOptions, BalloonRenderResult, BalloonType, Bookmark, BoundingBox, BranchChoice, BubbleStyle, BubbleTail, CameraMove, CameraMovePath, CameraState, CameraZoomProfile, CanvasBackground, CanvasCameraPolicy, CanvasDecoration, CanvasFitMode, CanvasFreeRoam, CanvasLayout, CanvasOverviewPolicy, CanvasPlacement, CanvasRevealMode, Chapter, Character$1 as Character, ContentWarning, Creator, DecisionEvent, DeepLinkTarget, DeviceVariables, Edge, EffectiveVideoConfig, EntitlementAdapter$1 as EntitlementAdapter, EntitlementContext, EntitlementErrorCode, EntitlementSnapshot, EntitlementSnapshotResponse, EntitlementStatus, EntitlementVariables, ErrorEvent$1 as ErrorEvent, EvaluatorEntitlementType, EvaluatorRule, EvaluatorScope, ExtraImage, ExtraItem, Extras, FormatView, Graph, HideBorderConfig, Hotspot, HotspotAction, HotspotCircle, HotspotGoToAction, HotspotOpenExtrasAction, HotspotOpenModalAction, HotspotPluginEventAction, HotspotPolygon, HotspotRect, HotspotSetVariablesAction, HotspotShape, HotspotUiEffect, HttpEntitlementAdapterConfig, ImageLayer, ImageVariant, JsonLogic, JsonLogicExpression, JsonValue, JsonVariant, Layer, LayerKind, LayerViewMode, LocaleCode, LocalizedString, LockReason, Meta, Mutation, MutationOperation, NavigationPath, NodeMetadata, NormalizedPoint, NormalizedRect, OutputFormat, OutputPreset, OverlayState, Page, PageLayout, PageVisual, Panel, PanelAnimations, PanelAudioRole, PanelAudioTrack, PanelChangeEvent, PanelPartial, PanelPlacement, PanelRef, PanelVariant, PanelWaveManifest, PanelwaveHeader, Paywall, PaywallAction, PaywallEvent, PaywallGate$1 as PaywallGate, PaywallProduct, PaywallRule, PlaybackState, PlayerError, PlayerErrorCode, PlayerEventData, PlayerLocation, PlayerOptions, PlayerPanelChangeEvent, PlayerPreferences, PlayerState, PlayerStatistics, PlayerView, PluginInstance$1 as PluginInstance, PluginLayer, PreferenceVariables, PreloadItem, PreloadPriority, PreloadSettings, PreloadStatus$1 as PreloadStatus, PreviewInfo, PurchaseInfo, ReadingProgress, ResolvedPanel, ResolvedPanelAudio, ScreenClass, SequenceAudioTrack, SequencedVideo, SequencedVideoInfo, Settings, SpeechBubble, StagePlacement, SubtitleVariant, TailConfig, TailCurve, TailOptions, TextLayer, TextStyle, Tracking, TrackingConfig$1 as TrackingConfig, TrackingEvent, Transform, Transition, TraversalOptions, TraversalResult, UIDefaults, UISettings, UserInfo, UserVariables, VariableChangeEvent, VariableContext, VariableDefinition, VariableMutation, VariableScope, VariableStore, VariableType, VariableValidationResult, Variables, VariantContext, VectorVariant, VideoEvent, VideoLayer, VideoPlayMode, VideoPoster, VideoStartMode, VideoState, VideoStatus, VideoTrackingPayload, VideoTrigger, VideoVariant, ViewMode, ViewportState, VisibilityChange, WorldPoint, WorldRect };
+export { ANONYMOUS_READER, ActionModalComponent, AgeGateComponent, AssetUrlService, AudioEngineService, BranchChooserComponent, CANVAS_PANEL_BUDGET, CanvasCameraService, CanvasStageComponent, ComicBalloon, DEFAULT_BALLOON_CONFIG, DEFAULT_PAGE_BACKGROUND, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_VIDEO_MUTED, DEFAULT_VIDEO_PLAY_MODE, DEFAULT_VIDEO_START_MODE, EntitlementError, EntitlementService, ExportService, FlowEngineService, HotspotActionService, HotspotsOverlayComponent, HttpEntitlementAdapter, ImageCacheService, LOCATION_PARAMS, ManifestService, MockEntitlementAdapter, NullEntitlementAdapter, PANEL_AUDIO_LEAVE_FADE_MS, PanelAudioService, PaywallOverlayComponent, PaywallService, PlayerComponent, PlayerEvent, PlayerService, PlayerShellComponent, PlayerStateService, PluginHostService, PluginSandboxComponent, PreloadService, PwIconComponent, RESERVED_NAMESPACES, SEQUENCE_AUDIO_LEAVE_FADE_MS, SequenceAudioService, SpeechBubblesComponent, THUMBNAIL_WIDTH, TrackingService, TranslationService, UserGestureService, VISIBILITY_THRESHOLD, VariableStoreService, VideoControllerService, VideoLayerComponent, VideoSequencerService, VisibilityService, applyVariantOverrides, balloonConfigToRenderOptions, balloonConfigToTailOptions, buildWorkTimeline, busForRole, chapterOrderFromManifest, coverImageSrc, createBalloon, cuesForPanel, evaluatePanelAccess, evaluateWorkAccess, findWorkGateRule, fromManifestRule, isExtraLocked, isLockedPanel, locationUrl, mergeBalloonConfig, pageAspectRatio, pageFormatOf, pageFormatsOf, pagesForFormat, panelThumbnailSrc, parseLocationSearch, pickPageFormat, rankPageFormats, readingOrderFromManifest, resolveMuted, resolvePageBackground, resolvePanelVariant, resolvePanels, resolvePlayMode, resolveStartMode, resolveTrackRanges, resolveVideoConfig, rulesFromManifest, satisfiesRule, screenClassFor, selectVariant, toEntitlementStatus };
+export type { AccessDecision, AgeVerificationResult, AnimatableProperty, AnimationEasing, AnimationKeyframe, AssetBase, AssetCatalogItem, AssetCatalogItemAudio, AssetCatalogItemImage, AssetCatalogItemJson, AssetCatalogItemPluginPayload, AssetCatalogItemSubtitle, AssetCatalogItemVector, AssetCatalogItemVideo, AssetCategory, AssetCommon, AssetRef, AssetReference, AssetVariant, Assets, AudioLayer, AudioRole, AudioTrack, AudioVariant, BalloonConfig, BalloonConfigOverride, BalloonOptions, BalloonRenderResult, BalloonType, Bookmark, BoundingBox, BranchChoice, BubbleStyle, BubbleTail, CameraMove, CameraMovePath, CameraState, CameraZoomProfile, CanvasBackground, CanvasCameraPolicy, CanvasDecoration, CanvasFitMode, CanvasFreeRoam, CanvasLayout, CanvasOverviewPolicy, CanvasPlacement, CanvasRevealMode, Chapter, Character$1 as Character, ContentWarning, Creator, DecisionEvent, DeepLinkTarget, DeviceVariables, Edge, EffectiveVideoConfig, EntitlementAdapter$1 as EntitlementAdapter, EntitlementContext, EntitlementErrorCode, EntitlementSnapshot, EntitlementSnapshotResponse, EntitlementStatus, EntitlementVariables, ErrorEvent$1 as ErrorEvent, EvaluatorEntitlementType, EvaluatorRule, EvaluatorScope, ExtraImage, ExtraItem, Extras, FormatView, Graph, HideBorderConfig, Hotspot, HotspotAction, HotspotCircle, HotspotGoToAction, HotspotOpenExtrasAction, HotspotOpenModalAction, HotspotPluginEventAction, HotspotPolygon, HotspotRect, HotspotSetVariablesAction, HotspotShape, HotspotUiEffect, HttpEntitlementAdapterConfig, ImageLayer, ImageVariant, JsonLogic, JsonLogicExpression, JsonValue, JsonVariant, Layer, LayerKind, LayerViewMode, LocaleCode, LocalizedString, LockReason, Meta, Mutation, MutationOperation, NavigationPath, NodeMetadata, NormalizedPoint, NormalizedRect, OutputFormat, OutputPreset, OverlayState, Page, PageLayout, PageVisual, Panel, PanelAnimations, PanelAudioRole, PanelAudioTrack, PanelChangeEvent, PanelCue, PanelPartial, PanelPlacement, PanelRef, PanelVariant, PanelWaveManifest, PanelwaveHeader, Paywall, PaywallAction, PaywallEvent, PaywallGate$1 as PaywallGate, PaywallProduct, PaywallRule, PlaybackState, PlayerError, PlayerErrorCode, PlayerEventData, PlayerLocation, PlayerOptions, PlayerPanelChangeEvent, PlayerPreferences, PlayerState, PlayerStatistics, PlayerView, PluginInstance$1 as PluginInstance, PluginLayer, PreferenceVariables, PreloadItem, PreloadPriority, PreloadSettings, PreloadStatus$1 as PreloadStatus, PreviewInfo, PurchaseInfo, ReadingProgress, ResolvedPanel, ResolvedPanelAudio, ScreenClass, SequenceAudioTrack, SequencedVideo, SequencedVideoInfo, Settings, SpeechBubble, StagePlacement, SubtitleVariant, TailConfig, TailCurve, TailOptions, TextLayer, TextStyle, TimelineEntry, TrackRange, Tracking, TrackingConfig$1 as TrackingConfig, TrackingEvent, Transform, Transition, TraversalOptions, TraversalResult, UIDefaults, UISettings, UserInfo, UserVariables, VariableChangeEvent, VariableContext, VariableDefinition, VariableMutation, VariableScope, VariableStore, VariableType, VariableValidationResult, Variables, VariantContext, VectorVariant, VideoEvent, VideoLayer, VideoPlayMode, VideoPoster, VideoStartMode, VideoState, VideoStatus, VideoTrackingPayload, VideoTrigger, VideoVariant, ViewMode, ViewportState, VisibilityChange, WorkTimeline, WorldPoint, WorldRect };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panelwave/player",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Open-source Angular library for PanelWave interactive graphic novels",
   "keywords": [
     "angular",