animot-presenter 0.5.16 → 0.5.18

package/README.md

@@ -358,9 +358,24 @@ export class DemoComponent implements AfterViewInit {
 | `keyboard`     | `boolean` | `true`  | Enable arrow key navigation              |
 | `duration`     | `number`  | —       | Override all transition durations (ms)   |
 | `start-slide`  | `number`  | `0`     | Initial slide index                      |
+| `mute-narration` | `boolean` | `false` | Force-disable per-slide voice narration regardless of the project's `settings.narrationEnabled`. Use on previews / gallery cards where audio would be intrusive. |
 
 **Note:** `data` can only be set via JavaScript property, not as an HTML attribute.
 
+### Per-slide voice narration
+
+Projects with `settings.narrationEnabled: true` and per-slide `narration` clips
+play voice-over alongside slide changes. Narration is bound to the deck's play
+state — pressing the play button starts narration, pause stops it. To disable
+narration on a specific embed regardless of the project's setting, set
+`mute-narration`.
+
+Recommended pattern for share-link / hero usage with narration: omit `autoplay`
+(the deck loads paused) so the viewer's first click on Play doubles as the
+gesture browsers require to unlock audio. Embedded gallery / preview surfaces
+where audio would be intrusive should pass `mute-narration` and keep
+`autoplay`.
+
 ## Events
 
 | Event          | Detail                        | Description                          |

package/dist/AnimotPresenter.svelte

@@ -155,7 +155,7 @@
 	let {
 		src, data, autoplay = false, loop = false, controls = true, arrows = false,
 		progress: showProgress = true, keyboard = true, duration: durationOverride,
-		startSlide = 0, class: className = '', onslidechange, oncomplete
+		startSlide = 0, muteNarration = false, class: className = '', onslidechange, oncomplete
 	}: AnimotPresenterProps = $props();
 
 	// State
@@ -199,6 +199,7 @@
 	// the user's click on the play control is itself the unlocking gesture.
 	let narrationAudio: HTMLAudioElement | null = null;
 	function playNarrationForSlide(index: number) {
+		if (muteNarration) return;
 		if (!project?.settings?.narrationEnabled) return;
 		const slide = project?.slides?.[index];
 		if (narrationAudio) {
@@ -558,6 +559,12 @@
 		currentSlideIndex = 0;
 		isTransitioning = false;
 
+		// Restart narration on loop. Setting `currentSlideIndex = 0` above
+		// is a no-op for single-slide decks (was already 0) so the play-state
+		// effect doesn't re-fire on its own. Calling explicitly here covers
+		// both single- and multi-slide loops uniformly.
+		if (isAutoplay) playNarrationForSlide(0);
+
 		for (const element of firstSlide.canvas.elements) {
 			if (element.type === 'text') {
 				const textEl = element as TextElement;
@@ -578,10 +585,12 @@
 		const targetSlide = slides[targetIndex];
 		clearAllTypewriterAnimations();
 		cancelMotionPathLoops();
-		// Trigger per-slide narration only while the deck is actively
-		// playing. Manual nav while paused stays silent — narration is
-		// bound to the play button, not to every interaction.
-		if (isAutoplay) playNarrationForSlide(targetIndex);
+		// Manual arrow nav and the autoplay timer are both forms of "user
+		// is moving forward in the deck" — both should swap narration to
+		// the new slide. The pause button is what stops audio. Without
+		// this, clicking an arrow while paused would render the new slide
+		// silently, which feels broken.
+		playNarrationForSlide(targetIndex);
 		const transition = targetSlide.transition;
 		const duration = durationOverride ?? transition.duration;
 		transitionDurationMs = duration;