presently 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42f99b653f49a0ac23d4c6b49314cde4ef814e70a7d274c7d67914e4f707514d
-  data.tar.gz: f308373c9741dad960682283d52df1d34e285e32e0c9155cd0911d3e62405562
+  metadata.gz: 532d867fea4dad3add38479e76432b7eabfe6769d1f45930cf6c3be61174648e
+  data.tar.gz: e197012bf34d8708eeb012205e07289a392a2263b29045a4d052239d578c961f
 SHA512:
-  metadata.gz: 48116005297631e4fbdc4d06c1b83cfadb847d61dcb03ea60e603af4c28d9d0e678539fe114fbf6ce4f12e0fbc590281094e7fa40c2be003e9d488be31a25516
-  data.tar.gz: ed77bebb4005f828ab6b09c321cf075778a394706f0ff0bd6ffc2e2852e3c73ac2da3944e1ad7744cb82e3546702d0f81c4a966acc346f9c374b032f29100df9
+  metadata.gz: 5d2bbb05d71ba4939e5a4491ce039bff503fd276f7a18d2d13cfb0e21d07259d4f3748d3c7fb630ae53544afafa0807c688f95e8b2c3954870620600f72692ba
+  data.tar.gz: 5d6052ff6a37f309cefc28fd6d9fe5fb15a46fbdf08bd1981959546e398a3a5536b7fdf6377af9459fc613d2d42cdb69ac8f610f64828985afb3884a7d144c48

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/bake/presently/rehearse.rb

@@ -21,8 +21,8 @@ end
 #
 # @parameter slides_root [String] The slides directory. Default: `slides`.
 # @parameter speaker [String | Nil] Only rehearse slides for this speaker.
-# @parameter from [String | Nil] Substring match — start at the first slide whose filename contains this.
-# @parameter to [String | Nil] Substring match — stop after the first slide whose filename contains this.
+# @parameter from [String | Nil] Substring match — start at the first slide whose relative path contains this.
+# @parameter to [String | Nil] Substring match — stop after the first slide whose relative path contains this.
 # @parameter resume [Boolean] Resume from the slide after the last one recorded in the log. Keeps prior records and appends new ones.
 # @parameter log [String] Path to write the JSON log. Default: `tmp/rehearsal.json`.
 def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: false, log: "tmp/rehearsal.json")
@@ -31,12 +31,12 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 	slides = slides.select{|slide| slide.speaker == speaker} if speaker
 	
 	if from
-		start_index = slides.index{|slide| File.basename(slide.path).include?(from)}
+		start_index = slides.index{|slide| slide.path.include?(from)}
 		slides = slides[start_index..] if start_index
 	end
 	
 	if to
-		end_index = slides.index{|slide| File.basename(slide.path).include?(to)}
+		end_index = slides.index{|slide| slide.path.include?(to)}
 		slides = slides[..end_index] if end_index
 	end
 	
@@ -49,7 +49,7 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 		
 		prior_records = JSON.parse(File.read(log), symbolize_names: true)
 		last_path = prior_records.last&.dig(:path)
-		resume_index = slides.index{|slide| File.basename(slide.path) == last_path}
+		resume_index = slides.index{|slide| slide.path == last_path}
 		
 		if resume_index.nil?
 			puts "Last rehearsed slide (#{last_path}) not found in current slide set. Nothing to resume."
@@ -81,14 +81,14 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 	records = []
 	offset = prior_records.length
 	slides.each_with_index do |slide, index|
-		basename = File.basename(slide.path)
+		relative_path = slide.path
 		headline = extract_headline(slide)
 		absolute = offset + index + 1
 		total = offset + slides.length
 		
 		puts
 		puts "─" * 72
-		puts "[#{absolute}/#{total}] #{basename}  planned: #{format_duration(slide.duration)}  speaker: #{slide.speaker || "—"}"
+		puts "[#{absolute}/#{total}] #{relative_path}  planned: #{format_duration(slide.duration)}  speaker: #{slide.speaker || "—"}"
 		puts "  #{headline}" unless headline.empty?
 		if slide.notes
 			notes = slide.notes.to_commonmark.strip
@@ -105,7 +105,7 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 		
 		records << {
 			index: absolute,
-			path: basename,
+			path: relative_path,
 			speaker: slide.speaker,
 			planned: slide.duration,
 			actual: elapsed.round(1),

data/bake/presently/slides.rb

@@ -58,7 +58,7 @@ def speakers(slides_root: "slides")
 		puts "#{speaker} — #{format_duration(total_seconds)}"
 		
 		slides.each do |slide|
-			puts "  #{format_duration(slide.duration)}  #{slide.title}  (#{File.basename(slide.path)})"
+			puts "  #{format_duration(slide.duration)}  #{slide.title}  (#{slide.path})"
 		end
 		
 		puts
@@ -69,9 +69,10 @@ end
 
 # Renumber slide files sequentially with a consistent step size.
 #
-# Renames all `.md` files in the slides directory to have sequential
+# Renames all `.md` files directly in the given directory to have sequential
 # numeric prefixes (010, 020, 030, ...), preserving their current order.
-# The descriptive part of the filename (after the number prefix) is kept.
+# The descriptive part of the filename (after the number prefix) is kept. It
+# does not recurse; pass a nested directory as `slides_root` to renumber it.
 #
 # @parameter slides_root [String] The slides directory. Default: `slides`.
 # @parameter step [Integer] The step between slide numbers. Default: `10`.

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

@@ -32,7 +32,27 @@ $ mkdir slides
 
 ### Writing Slides
 
-Each slide is a Markdown file in the `slides/` directory. Files are ordered alphabetically, so prefix them with numbers:
+Each slide is a Markdown file in the `slides/` directory. Files are ordered by path, and every directory and slide filename must begin with a numeric prefix:
+
+``` text
+slides/
+├── 010-welcome.md
+├── 020-performance/
+│   ├── 010-introduction.md
+│   └── 020-results.md
+└── 030-conclusion.md
+```
+
+This allows related slides to be grouped in nested directories while retaining an unambiguous presentation order. Markdown files with any unnumbered path component, such as `slides/shared/example.md`, are not treated as slides and can be used for included content.
+
+The `presently:slides:renumber` task only renumbers files directly inside the selected directory. Run it without arguments for the top-level slides, or pass a nested directory explicitly:
+
+``` shell
+$ bake presently:slides:renumber
+$ bake presently:slides:renumber slides_root=slides/020-performance
+```
+
+A slide file contains Markdown with optional frontmatter and presenter notes:
 
 ``` markdown
 ---