presently 0.16.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c2eaa843e93a1ef3f3c97b0e89c80a3ee4484ddbee4c105ca39bc7c324671ea
-  data.tar.gz: bc27aa664ca531b38da8b807e3fcb438a41c4338a180c1ddd39fc1daa0c549ed
+  metadata.gz: 76e4ab0cea03d4eefe8864d4c81f0193615ba5bb4548d65d19fd93992408a746
+  data.tar.gz: b2315554cb96689cf429c04d3a914525cc3294f5e01bb1cc39b0cf7a475d8b6d
 SHA512:
-  metadata.gz: 98959ac207c29fa8a4bf444e0d1e476e584183615d04abed09c8f74cda3a338ed61f9517f67d5e7e5bb40aa624c352100bf1c2f36c61663a81f61ec509fe52d8
-  data.tar.gz: 30ca2a30e72d1f0c0dbc71b31786349ecd8d8c70eae5d69f29e701e77cd2f39487909a71a4699b2be9b70169cc170065313da35e46394ab92d0b378f3849e38a
+  metadata.gz: 34fbbeee043bbdd4241049e639388661808245d0d3001256d979745199074c30a867ffc4782f30a728d494453fdadf723589ff3f44f44f08a2dd65b11bdb3b50
+  data.tar.gz: eb40ee8ba2bfa106b86e9641ece873ae27043e137c0fe3ae69ff714e24562b1b01d4a58de15681655e74348a4bcbec9f965c8bc6ac65166d63bf7c4378c58282

data/bake/presently/export.rb

@@ -6,6 +6,7 @@
 def initialize(context)
 	super
 	
+	require "base64"
 	require "fileutils"
 	require "uri"
 end
@@ -23,12 +24,7 @@ end
 # @parameter timing [Boolean] Include slide duration and elapsed time. Default: `true`.
 # @parameter timeout [Integer] Seconds to wait for the page to signal readiness. Default: `60`.
 def pdf(output: "presentation.pdf", slides_root: "slides", notes: true, speaker: true, timing: true, slide_width_px: 1920, slide_height_px: 1080, notes_height_px: 300, timeout: 60)
-	require "async"
-	require "async/http/endpoint"
-	require "async/service"
-	require "async/webdriver"
 	require "presently"
-	require "presently/environment/application"
 	
 	page_size = Presently::Export::PageSize.new(
 		slide_width_px:  slide_width_px,
@@ -43,6 +39,121 @@ def pdf(output: "presentation.pdf", slides_root: "slides", notes: true, speaker:
 		slide_width_px: slide_width_px, slide_height_px: slide_height_px, notes_height_px: notes_height_px
 	)
 	
+	with_browser_session(slides_root: slides_root, timeout: timeout) do |session, base_url|
+		session.resize_window(
+			page_size.slide_width_px,
+			page_size.slide_height_px
+		)
+		
+		session.navigate_to("#{base_url}/export?#{query}")
+		
+		# Block until export.js dispatches presently:ready.
+		session.execute_async(<<~JS)
+			const done = arguments[arguments.length - 1];
+			if (window.__PRESENTLY_READY) { done(); return; }
+			document.addEventListener('presently:ready', () => done(), {once: true});
+		JS
+		
+		pdf_data = session.print(
+			background:    true,
+			margin:        {top: 0, bottom: 0, left: 0, right: 0},
+			page:          {width: page_size.slide_width_cm, height: page_height_cm},
+			shrink_to_fit: false
+		)
+		
+		FileUtils.mkdir_p(File.dirname(File.expand_path(output)))
+		File.write(output, pdf_data, mode: "wb")
+	end
+	
+	return {path: output}
+end
+
+# Export the narrated presentation to an MP4 video.
+#
+# This uses Chromium's experimental `Page.startScreenRecording` DevTools
+# command. Until that command reaches Chrome for Testing, pass matching
+# Chromium and ChromeDriver paths explicitly (or through the
+# `PRESENTLY_CHROME_PATH` and `PRESENTLY_CHROMEDRIVER_PATH` environment
+# variables).
+#
+# @parameter output [String] Output MP4 path. Default: `presentation.mp4`.
+# @parameter slides_root [String] The slides directory. Default: `slides`.
+# @parameter width [Integer] Maximum video width. Default: `1920`.
+# @parameter height [Integer] Maximum video height. Default: `1080`.
+# @parameter frame_rate [Integer] Maximum video frame rate. Default: `30`.
+# @parameter timeout [Integer] Seconds to wait for the playback page to load. Default: `60`.
+# @parameter duration_limit [Integer] Maximum presentation duration in seconds. Default: `3600`.
+# @parameter browser_version [String] Chrome for Testing version used when explicit paths are omitted. Default: `canary`.
+# @parameter browser_path [String | Nil] Path to a Chromium executable supporting screen recording.
+# @parameter driver_path [String | Nil] Path to a matching ChromeDriver executable.
+def video(output: "presentation.mp4", slides_root: "slides", width: 1920, height: 1080, frame_rate: 30, timeout: 60, duration_limit: 3600, browser_version: "canary", browser_path: nil, driver_path: nil)
+	browser_path ||= ENV["PRESENTLY_CHROME_PATH"]
+	driver_path ||= ENV["PRESENTLY_CHROMEDRIVER_PATH"]
+	
+	with_browser_session(
+		slides_root: slides_root,
+		timeout: timeout,
+		script_timeout: duration_limit,
+		browser_version: browser_version,
+		browser_path: browser_path,
+		driver_path: driver_path,
+		chrome_arguments: ["--autoplay-policy=no-user-gesture-required", "--hide-scrollbars"]
+	) do |session, base_url|
+		resize_viewport(session, width, height)
+		session.navigate_to("#{base_url}/playback?autoplay=false&controls=false")
+		
+		ready = session.execute_async(<<~JS)
+			const done = arguments[arguments.length - 1];
+			if (window.__PRESENTLY_PLAYBACK_ERROR) { done({error: window.__PRESENTLY_PLAYBACK_ERROR}); return; }
+			if (window.__PRESENTLY_PLAYBACK_READY) { done({ready: true}); return; }
+			document.addEventListener('presently:playback-error', event => done({error: event.detail.message}), {once: true});
+			document.addEventListener('presently:playback-ready', () => done({ready: true}), {once: true});
+		JS
+		
+		raise "Playback preparation failed: #{ready["error"]}" if ready["error"]
+		
+		recording_started = false
+		stream = nil
+		playback = nil
+		
+		begin
+			devtools(session, "Page.startScreenRecording", audio: true, maxWidth: width, maxHeight: height, frameRate: frame_rate)
+			recording_started = true
+			
+			session.execute("window.__PRESENTLY_PLAYBACK_START();")
+			playback = session.execute_async(<<~JS)
+				const done = arguments[arguments.length - 1];
+				if (window.__PRESENTLY_PLAYBACK_ERROR) { done({error: window.__PRESENTLY_PLAYBACK_ERROR}); return; }
+				if (window.__PRESENTLY_PLAYBACK_FINISHED) { done({finished: true}); return; }
+				document.addEventListener('presently:playback-error', event => done({error: event.detail.message}), {once: true});
+				document.addEventListener('presently:playback-finished', () => done({finished: true}), {once: true});
+			JS
+		ensure
+			if recording_started
+				stream = devtools(session, "Page.stopScreenRecording")["stream"]
+			end
+		end
+		
+		raise "Playback failed: #{playback["error"]}" if playback&.dig("error")
+		raise "Chromium did not return the recorded video stream!" unless stream
+		
+		write_devtools_stream(session, stream, output)
+	end
+	
+	return {path: output}
+end
+
+private
+
+def with_browser_session(slides_root:, timeout:, script_timeout: timeout, browser_version: "stable", browser_path: nil, driver_path: nil, chrome_arguments: [])
+	require "async"
+	require "async/http/endpoint"
+	require "async/service"
+	require "async/webdriver"
+	require "presently/environment/application"
+	
+	result = nil
+	
 	Async do |task|
 		# Bind port 0 first so we know the actual address before starting the server.
 		bound_endpoint = Async::HTTP::Endpoint.parse("http://localhost:0").bound
@@ -55,7 +166,7 @@ def pdf(output: "presentation.pdf", slides_root: "slides", notes: true, speaker:
 				endpoint: Async::HTTP::Endpoint.parse("http://localhost", bound_endpoint)
 			)
 			
-			# PDF export always requires an HTTP server, regardless of the configured
+			# Export always requires an HTTP server, regardless of the configured
 			# Lively transport:
 			transport = environment.with(environment.evaluator.http_environment)
 			evaluator = transport.evaluator
@@ -63,53 +174,22 @@ def pdf(output: "presentation.pdf", slides_root: "slides", notes: true, speaker:
 			server_task = task.async{server.run}
 			
 			begin
-				# Derive the actual base URL from the bound socket address.
-				base_url = nil
-				bound_endpoint.local_address_endpoint.each do |endpoint|
-					address = endpoint.address
-					host = address.ipv6? ? "[#{address.ip_address}]" : address.ip_address
-					base_url = "http://#{host}:#{address.ip_port}"
-					break
-				end
-				
-				export_url = "#{base_url}/export?#{query}"
-				
-				bridge = Async::WebDriver::Bridge::Chrome.for(:stable)
+				base_url = export_base_url(bound_endpoint)
+				bridge = chrome_bridge(browser_version, browser_path, driver_path)
 				driver = bridge.start
 				
 				begin
 					client = Async::WebDriver::Client.open(driver.endpoint)
 					
 					begin
-						session = client.session(bridge.default_capabilities)
+						capabilities = bridge.default_capabilities
+						capabilities[:alwaysMatch][:"goog:chromeOptions"][:args].concat(chrome_arguments)
+						session = client.session(capabilities)
 						
 						begin
-							session.resize_window(
-								page_size.slide_width_px,
-								page_size.slide_height_px
-							)
-							
 							session.page_load_timeout = timeout * 1000
-							session.script_timeout = timeout * 1000
-							
-							session.navigate_to(export_url)
-							
-							# Block until export.js dispatches presently:ready.
-							session.execute_async(<<~JS)
-								const done = arguments[arguments.length - 1];
-								if (window.__PRESENTLY_READY) { done(); return; }
-								document.addEventListener('presently:ready', () => done(), {once: true});
-							JS
-							
-							pdf_data = session.print(
-								background:    true,
-								margin:        {top: 0, bottom: 0, left: 0, right: 0},
-								page:          {width: page_size.slide_width_cm, height: page_height_cm},
-								shrink_to_fit: false
-							)
-							
-							FileUtils.mkdir_p(File.dirname(File.expand_path(output)))
-							File.write(output, pdf_data, mode: "wb")
+							session.script_timeout = script_timeout * 1000
+							result = yield(session, base_url)
 						ensure
 							session.close
 						end
@@ -128,5 +208,67 @@ def pdf(output: "presentation.pdf", slides_root: "slides", notes: true, speaker:
 		end
 	end
 	
-	return {path: output}
+	return result
+end
+
+def chrome_bridge(browser_version, browser_path, driver_path)
+	if browser_path || driver_path
+		options = {}
+		options[:browser_path] = File.expand_path(browser_path) if browser_path
+		options[:driver_path] = File.expand_path(driver_path) if driver_path
+		
+		Async::WebDriver::Bridge::Chrome.new(**options)
+	else
+		Async::WebDriver::Bridge::Chrome.for(browser_version.to_sym)
+	end
+end
+
+def export_base_url(bound_endpoint)
+	bound_endpoint.local_address_endpoint.each do |endpoint|
+		address = endpoint.address
+		host = address.ipv6? ? "[#{address.ip_address}]" : address.ip_address
+		return "http://#{host}:#{address.ip_port}"
+	end
+	
+	raise "Could not determine the export server address!"
+end
+
+def resize_viewport(session, width, height)
+	# WebDriver sizes the outer window, while screen recording captures the page
+	# viewport. Measure the browser decoration after an initial resize and
+	# compensate so the recorded video has the requested dimensions.
+	session.resize_window(width, height)
+	dimensions = session.execute(<<~JS)
+		return {outerWidth, outerHeight, innerWidth, innerHeight};
+	JS
+	
+	session.resize_window(
+		width + dimensions["outerWidth"] - dimensions["innerWidth"],
+		height + dimensions["outerHeight"] - dimensions["innerHeight"]
+	)
+end
+
+def devtools(session, command, **parameters)
+	session.post("goog/cdp/execute", {cmd: command, params: parameters})
+rescue Async::WebDriver::Error => error
+	raise "Chromium does not support #{command}: #{error.message}"
+end
+
+def write_devtools_stream(session, stream, output)
+	path = File.expand_path(output)
+	FileUtils.mkdir_p(File.dirname(path))
+	
+	begin
+		File.open(path, "wb") do |file|
+			loop do
+				chunk = devtools(session, "IO.read", handle: stream, size: 1024 * 1024)
+				data = chunk["data"]
+				data = Base64.strict_decode64(data) if chunk["base64Encoded"]
+				file.write(data)
+				break if chunk["eof"]
+			end
+		end
+	ensure
+		devtools(session, "IO.close", handle: stream)
+	end
 end

data/bake/presently/recordings.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+def initialize(context)
+	super
+	
+	require "pathname"
+	require "presently/recordings/normalizer"
+end
+
+# Normalize all completed slide recordings to a consistent loudness.
+#
+# Original recordings are preserved under `input_root`. Normalized WebM/Opus
+# files are written to the corresponding paths under `output_root`. Existing
+# outputs newer than their source are skipped unless `force` is enabled.
+#
+# @parameter input_root [String] Source recordings directory. Default: `audio`.
+# @parameter output_root [String] Normalized recordings directory. Default: `audio-normalized`.
+# @parameter integrated_loudness [Float] Target integrated loudness in LUFS. Default: `-16.0`.
+# @parameter true_peak [Float] Maximum true peak in dBTP. Default: `-1.5`.
+# @parameter loudness_range [Float] Target loudness range in LU. Default: `11.0`.
+# @parameter bitrate [String] Output Opus bitrate. Default: `128k`.
+# @parameter force [Boolean] Normalize recordings even when output is current. Default: `false`.
+# @parameter command [String] FFmpeg executable. Default: `ffmpeg`.
+def normalize(input_root: "audio", output_root: "audio-normalized", integrated_loudness: -16.0, true_peak: -1.5, loudness_range: 11.0, bitrate: "128k", force: false, command: "ffmpeg")
+	input_root = File.expand_path(input_root)
+	output_root = File.expand_path(output_root)
+	
+	if input_root == output_root
+		raise ArgumentError, "output_root must be different from input_root so originals are preserved!"
+	end
+	
+	files = Dir.glob(File.join(input_root, "**", "*.webm")).sort
+	if files.empty?
+		puts "No WebM recordings found under #{input_root}."
+		return {processed: 0, skipped: 0, output_root: output_root}
+	end
+	
+	normalizer = Presently::Recordings::Normalizer.new(command: command)
+	processed = 0
+	skipped = 0
+	
+	files.each do |input_path|
+		relative_path = Pathname.new(input_path).relative_path_from(Pathname.new(input_root)).to_s
+		output_path = File.join(output_root, relative_path)
+		
+		if !force && File.file?(output_path) && File.mtime(output_path) >= File.mtime(input_path)
+			puts "Skipping #{relative_path} (already normalized)."
+			skipped += 1
+			next
+		end
+		
+		print "Normalizing #{relative_path}... "
+		measurements = normalizer.normalize(
+			input_path,
+			output_path,
+			integrated_loudness: integrated_loudness,
+			true_peak: true_peak,
+			loudness_range: loudness_range,
+			bitrate: bitrate,
+		)
+		input = measurements.fetch(:input)
+		output = measurements.fetch(:output)
+		puts "#{input.fetch("input_i")} LUFS → #{output.fetch("input_i")} LUFS, #{output.fetch("input_tp")} dBTP"
+		processed += 1
+	end
+	
+	puts "Normalized #{processed} recording#{"s" unless processed == 1}; skipped #{skipped}."
+	return {processed: processed, skipped: skipped, output_root: output_root}
+end

data/context/animating-slides.md

@@ -25,7 +25,7 @@ slide.find("li").show(1)
 ```
 ~~~
 
-The script receives a `slide` object — an instance of the `Slide` class from `slide.js` — scoped to the current slide's body.
+The script receives a `slide` object — an instance of the `Slide` class exported by `@socketry/presently` — scoped to the current slide's body.
 
 If the script contains a syntax error or throws an exception, the error is logged to the browser console and the presentation continues unaffected.
 
@@ -194,6 +194,30 @@ All timeouts registered via `slide.after()` (and the underlying `slide.setTimeou
 
 The global `setTimeout` in slide scripts is also automatically tracked — you can use it directly and it will be cancelled on slide change.
 
+## Slide Lifetime and Cleanup
+
+Slide scripts can start resources other than timers, including audio, video, observers, animations, and event listeners. Use `slide.defer(callback)` to release those resources when the slide is deactivated:
+
+``` javascript
+const audio = new Audio("introduction.mp3")
+audio.play()
+
+slide.defer(() => {
+  audio.pause()
+})
+```
+
+Deferred callbacks run in reverse registration order when the slide changes. Registering a callback after the slide has already been deactivated runs it immediately, preventing asynchronously-created resources from escaping the slide's lifetime.
+
+The `slide.signal` getter exposes an `AbortSignal` which is aborted at the same time. Browser APIs which support abort signals can therefore be bound directly to the slide:
+
+``` javascript
+const button = slide.element.querySelector("button")
+button.addEventListener("click", handleClick, {signal: slide.signal})
+```
+
+Aborting the signal removes this event listener; it does not invoke `handleClick`. Use `slide.defer(...)` for resources which do not accept an `AbortSignal`.
+
 ## Looping Animations with `slide.loop()`
 
 To repeat an animation indefinitely, use `slide.loop()`. The callback receives a fresh `SlideContext` each iteration and can use `after()` to schedule steps in the same way as a regular chain. The loop waits for all steps to complete and then restarts, with an optional extra pause between iterations.

data/context/getting-started.md

@@ -79,6 +79,43 @@ Each slide has three parts:
 2. **Content** with Markdown headings that become named sections for the template.
 3. **Presenter notes** after a `---` separator in the body (optional).
 
+### Styling Slides
+
+CSS can be colocated with the slides it styles:
+
+``` text
+slides/
+├── style.css
+├── 010-introduction.md
+└── 020-scheduling/
+    ├── style.css
+    ├── 010-overview.md
+    ├── 020-queue.md
+    └── 020-queue.css
+```
+
+`slides/style.css` applies globally. A nested `style.css` applies to every slide below that directory, while a CSS file matching a Markdown filename applies only to that slide. In the example above, `020-scheduling/style.css` applies to both scheduling slides and `020-queue.css` applies only to `020-queue.md`.
+
+Presently automatically wraps nested and slide-specific stylesheets in an [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope) rule rooted at the rendered slide. Write these files as scoped CSS fragments containing ordinary style rules and nestable grouping rules such as `@media`, `@supports`, `@container`, and `@layer`. Keep stylesheet-level rules such as `@charset`, `@import`, and `@namespace`, and globally named definitions such as `@font-face`, `@keyframes`, and `@property`, in the root `slides/style.css` or the existing `public/_static/custom.css`.
+
+Relative images and fonts remain adjacent to the stylesheet that uses them:
+
+``` css
+.architecture {
+	background-image: url("architecture.svg");
+}
+```
+
+Presently uses `protocol-media-registry` to determine asset content types. Files with unrecognized media types are not served.
+
+Relative images embedded in Markdown resolve from the Markdown file's directory, including images in included Markdown files:
+
+``` markdown
+![Architecture](architecture.svg)
+```
+
+Presently loads each discovered stylesheet once in deterministic presentation order. Directory styles are loaded from parent to child before the matching slide sidecar, so more specific styles naturally appear later in the cascade. The same stylesheets are used by the display, presenter, recorder, playback, and export interfaces.
+
 ### Running the Presentation
 
 Start the server from your presentation directory:
@@ -87,13 +124,66 @@ Start the server from your presentation directory:
 $ presently
 ```
 
-Then open two browser windows:
+Open the launcher, or go directly to one of the presentation interfaces:
 
-- `http://localhost:9292/` — the audience display.
+- `http://localhost:9292/` — the interface launcher.
+- `http://localhost:9292/display` — the audience display.
 - `http://localhost:9292/presenter` — the presenter console.
+- `http://localhost:9292/record` — the slide narration recorder.
+- `http://localhost:9292/playback` — automatic playback with recorded narration.
 
 Advancing slides in either window updates both in real-time via WebSockets.
 
+### Recording Slide Narration
+
+The recording interface is separate from the presenter console because narration is an authoring workflow: each slide can be recorded, reviewed, retaken, and explicitly saved without changing the live presentation controls.
+
+Presently records WebM/Opus audio using the browser microphone, preserving its dynamics for offline normalization. A short delayed audio pipeline excludes approximately 100 milliseconds around the mouse clicks at the beginning and end. Saved recording paths mirror their slide paths under the presentation's `audio/` directory:
+
+``` text
+slides/020-problem/010-overview.md
+audio/020-problem/010-overview.webm
+```
+
+To record narration:
+
+1. Open `http://localhost:9292/record` in a browser with WebM/Opus `MediaRecorder` support.
+2. Select the slide and press **Record**.
+3. Press **Stop**, then review the recording with the audio player.
+4. Press **Save** to replace that slide's existing narration.
+
+Navigating away before saving discards the retake and preserves the previously saved recording.
+
+To normalize completed takes to a consistent `-16 LUFS` target, install FFmpeg and run:
+
+``` shell
+bundle exec bake presently:recordings:normalize
+```
+
+Originals remain under `audio/`; normalized WebM/Opus copies are written under `audio-normalized/` using the same relative paths. The task skips outputs that are newer than their source, so it can be rerun after recording additional slides.
+
+### Playing Recorded Narration
+
+Open `http://localhost:9292/playback` after every slide has a recording. Press **Start presentation** and Presently will play each narration track, run the slide's script, preserve its transition, and advance when the narration ends. Normalized recordings are preferred, with the corresponding original recording used as a fallback.
+
+For browser automation or video capture, open:
+
+``` text
+http://localhost:9292/playback?autoplay=true&controls=false
+```
+
+The playback page sets `window.__PRESENTLY_PLAYBACK_READY` after its slides, fonts, syntax highlighting, and audio metadata are loaded. It sets `window.__PRESENTLY_PLAYBACK_FINISHED` when the final narration ends. It also dispatches `presently:playback-ready` and `presently:playback-finished` events for event-driven integrations.
+
+To export the narrated presentation directly to MP4, use a Chromium and matching ChromeDriver build that supports the experimental `Page.startScreenRecording` DevTools command:
+
+``` shell
+PRESENTLY_CHROME_PATH=/path/to/chromium \
+PRESENTLY_CHROMEDRIVER_PATH=/path/to/chromedriver \
+bundle exec bake presently:export:video output=presentation.mp4
+```
+
+The defaults are 1920×1080 at up to 30 frames per second. The exporter starts an isolated Presently server, waits for playback to become ready, records until the final narration ends, and writes Chromium's MP4 stream to the selected output path.
+
 ### Keyboard Controls
 
 - **Arrow Right / Space / Page Down** — next slide.