@machinal/scenes 0.0.0-stage → 0.1.1

package/renderer/browser.go

@@ -0,0 +1,116 @@
+package sceneengine
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"sync"
+	"time"
+
+	"github.com/chromedp/chromedp"
+)
+
+const (
+	defaultConcurrency  = 2
+	maxConcurrency      = 16
+	defaultFrameTimeout = 30 * time.Second
+)
+
+// Renderer owns one Chromium process reused across sequential render jobs.
+// Each active frame has an exclusive tab; concurrent Render calls are rejected.
+type Renderer struct {
+	browser         context.Context
+	cancelBrowser   context.CancelFunc
+	cancelAllocator context.CancelFunc
+	options         Options
+	lease           chan struct{}
+	closeOnce       sync.Once
+	browserLog      *browserLog
+}
+
+// New starts a pinned browser whose lifetime is owned by ctx or Close.
+func New(ctx context.Context, options Options) (*Renderer, error) {
+	options, err := normalizeOptions(options)
+	if err != nil {
+		return nil, err
+	}
+	diagnostics := &browserLog{}
+	flags := append([]chromedp.ExecAllocatorOption{}, chromedp.DefaultExecAllocatorOptions[:]...)
+	flags = append(flags,
+		chromedp.CombinedOutput(diagnostics),
+		chromedp.ExecPath(options.BrowserExecutable),
+		chromedp.Flag("disable-background-timer-throttling", true),
+		chromedp.Flag("disable-renderer-backgrounding", true),
+		chromedp.Flag("disable-backgrounding-occluded-windows", true),
+		chromedp.Flag("force-color-profile", "srgb"),
+		chromedp.Flag("hide-scrollbars", true),
+		chromedp.Flag("mute-audio", true),
+	)
+	if options.NoSandbox {
+		flags = append(flags, chromedp.NoSandbox)
+	}
+	if options.EnableGPU {
+		flags = append(flags, chromedp.Flag("disable-gpu", false), chromedp.Flag("enable-gpu", true))
+	}
+	allocator, cancelAllocator := chromedp.NewExecAllocator(ctx, flags...)
+	browser, cancelBrowser := chromedp.NewContext(allocator)
+	renderer := &Renderer{browser: browser, cancelBrowser: cancelBrowser, cancelAllocator: cancelAllocator, options: options, lease: make(chan struct{}, 1), browserLog: diagnostics}
+	startupTimeout := time.AfterFunc(options.FrameTimeout, cancelBrowser)
+	defer startupTimeout.Stop()
+	if err := chromedp.Do(browser); err != nil {
+		renderer.Close()
+		return nil, diagnostics.wrap(fmt.Errorf("start Chromium: %w", err))
+	}
+	return renderer, nil
+}
+
+func normalizeOptions(options Options) (Options, error) {
+	if options.BrowserExecutable == "" {
+		return options, fmt.Errorf("BrowserExecutable is required; use a pinned Chrome Headless Shell binary")
+	}
+	if options.FFmpegExecutable == "" {
+		options.FFmpegExecutable = "ffmpeg"
+	}
+	ffmpeg, err := exec.LookPath(options.FFmpegExecutable)
+	if err != nil {
+		return options, fmt.Errorf("locate FFmpeg: %w", err)
+	}
+	options.FFmpegExecutable = ffmpeg
+	if options.X264Preset == "" {
+		options.X264Preset = "medium"
+	}
+	switch options.X264Preset {
+	case "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow":
+	default:
+		return options, fmt.Errorf("invalid x264 preset")
+	}
+	if options.EncoderThreads < 0 || options.EncoderThreads > 32 {
+		return options, fmt.Errorf("encoder threads must be between 0 (automatic) and 32")
+	}
+	if options.Concurrency == 0 {
+		options.Concurrency = defaultConcurrency
+	}
+	if options.Concurrency < 1 || options.Concurrency > maxConcurrency {
+		return options, fmt.Errorf("concurrency must be between 1 and %d", maxConcurrency)
+	}
+	if options.FrameTimeout == 0 {
+		options.FrameTimeout = defaultFrameTimeout
+	}
+	if options.FrameTimeout < 0 {
+		return options, fmt.Errorf("frame timeout must be positive")
+	}
+	for _, origin := range options.AllowedOrigins {
+		if _, err := parseOrigin(origin); err != nil {
+			return options, fmt.Errorf("allowed origin %q: %w", origin, err)
+		}
+	}
+	return options, nil
+}
+
+// Close cancels active jobs and releases the browser process; it is idempotent.
+func (r *Renderer) Close() {
+	r.closeOnce.Do(func() {
+		r.cancelBrowser()
+		r.cancelAllocator()
+	})
+}

package/renderer/browser_log.go

@@ -0,0 +1,36 @@
+package sceneengine
+
+import (
+	"bytes"
+	"fmt"
+	"sync"
+)
+
+const maxBrowserLogBytes = 8 << 10
+
+type browserLog struct {
+	mu     sync.Mutex
+	buffer []byte
+}
+
+func (l *browserLog) Write(data []byte) (int, error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.buffer = append(l.buffer, data...)
+	if len(l.buffer) > maxBrowserLogBytes {
+		l.buffer = bytes.Clone(l.buffer[len(l.buffer)-maxBrowserLogBytes:])
+	}
+	return len(data), nil
+}
+
+func (l *browserLog) wrap(err error) error {
+	if l == nil || err == nil {
+		return err
+	}
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if len(l.buffer) == 0 {
+		return err
+	}
+	return fmt.Errorf("%w\nChromium diagnostics:\n%s", err, l.buffer)
+}

package/renderer/browser_log_test.go

@@ -0,0 +1,48 @@
+package sceneengine
+
+import (
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+)
+
+func TestBrowserLogRetainsBoundedFailureDetails(t *testing.T) {
+	var log browserLog
+	data := []byte(strings.Repeat("x", maxBrowserLogBytes) + "\nNo space left on device")
+	written, err := log.Write(data)
+	if err != nil || written != len(data) {
+		t.Fatalf("write browser output: %d, %v", written, err)
+	}
+	if len(log.buffer) != maxBrowserLogBytes {
+		t.Fatalf("browser log has %d bytes", len(log.buffer))
+	}
+	cause := errors.New("capture frame 1405 failed")
+	failure := log.wrap(cause)
+	if !errors.Is(failure, cause) || !strings.HasSuffix(failure.Error(), "No space left on device") {
+		t.Fatalf("lost capture failure or browser diagnostic: %v", failure)
+	}
+}
+
+func TestBrowserLogWithoutOutputPreservesOriginalError(t *testing.T) {
+	cause := errors.New("capture failed")
+	for _, log := range []*browserLog{nil, {}} {
+		if log.wrap(cause) != cause {
+			t.Fatal("empty browser output changed the original error")
+		}
+	}
+}
+
+func TestBrowserLogSupportsConcurrentOutputAndFailures(t *testing.T) {
+	var log browserLog
+	var writers sync.WaitGroup
+	for range 4 {
+		writers.Go(func() {
+			for range 100 {
+				log.Write([]byte("browser diagnostic\n"))
+				log.wrap(errors.New("capture failed"))
+			}
+		})
+	}
+	writers.Wait()
+}

package/renderer/browser_test.go

@@ -0,0 +1,307 @@
+package sceneengine
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"image/png"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func browserFixture(t *testing.T, progress func(Progress)) (*Renderer, Request) {
+	t.Helper()
+	browser, ffmpeg, directory := os.Getenv("SCENE_BROWSER"), os.Getenv("SCENE_FFMPEG"), os.Getenv("SCENE_FIXTURE_DIR")
+	if browser == "" || ffmpeg == "" || directory == "" {
+		t.Skip("configure SCENE_BROWSER, SCENE_FFMPEG and SCENE_FIXTURE_DIR for native tests")
+	}
+	server := httptest.NewServer(http.FileServer(http.Dir(directory)))
+	t.Cleanup(server.Close)
+	ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
+	t.Cleanup(cancel)
+	renderer, err := New(ctx, Options{BrowserExecutable: browser, FFmpegExecutable: ffmpeg, Concurrency: 2, FrameTimeout: 10 * time.Second, Progress: progress})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(renderer.Close)
+	request := fixtureRequest()
+	request.URL = server.URL + "/scene.html"
+	request.Seed = "native-test"
+	request.Config.FPS = 12
+	request.Config.DurationInFrames = 24
+	return renderer, request
+}
+
+func TestBrowserDeterministicFrames(t *testing.T) {
+	renderer, request := browserFixture(t, nil)
+	worker, err := renderer.newWorker(context.Background(), request)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer worker.close()
+	first, err := worker.capture(context.Background(), 18)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := worker.capture(context.Background(), 3); err != nil {
+		t.Fatal(err)
+	}
+	repeated, err := worker.capture(context.Background(), 18)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertCapturePixelsEqual(t, first, repeated)
+	second, err := renderer.newWorker(context.Background(), request)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer second.close()
+	parallel, err := second.capture(context.Background(), 18)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertCapturePixelsEqual(t, first, parallel)
+}
+
+func assertCapturePixelsEqual(t *testing.T, first, second []byte) {
+	t.Helper()
+	a, err := png.Decode(bytes.NewReader(first))
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, err := png.Decode(bytes.NewReader(second))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if a.Bounds() != b.Bounds() {
+		t.Fatal("capture dimensions differ")
+	}
+	for y := a.Bounds().Min.Y; y < a.Bounds().Max.Y; y++ {
+		for x := a.Bounds().Min.X; x < a.Bounds().Max.X; x++ {
+			ar, ag, ab, aa := a.At(x, y).RGBA()
+			br, bg, bb, ba := b.At(x, y).RGBA()
+			if ar != br || ag != bg || ab != bb || aa != ba {
+				t.Fatalf("capture pixels differ at %d,%d: %d,%d,%d,%d vs %d,%d,%d,%d", x, y, ar, ag, ab, aa, br, bg, bb, ba)
+			}
+		}
+	}
+}
+
+func TestBrowserRenderVideoAndAudio(t *testing.T) {
+	renderer, request := browserFixture(t, nil)
+	root := t.TempDir()
+	audio := filepath.Join(root, "tone.wav")
+	generate := exec.Command(renderer.options.FFmpegExecutable, "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=440:duration=2", "-y", audio)
+	if data, err := generate.CombinedOutput(); err != nil {
+		t.Fatalf("create audio fixture: %v: %s", err, data)
+	}
+	request.Audio = []AudioTrack{{File: audio, Start: 0.5, Duration: 1}}
+	output := filepath.Join(root, "scene.mp4")
+	result, err := renderer.Render(context.Background(), request, output)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.HasAudio || result.Frames != 24 || result.Duration != 2 {
+		t.Fatalf("invalid result: %+v", result)
+	}
+	hash, size, err := fingerprint(output)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if hash != result.SHA256 || size != result.Size {
+		t.Fatal("manifest fingerprint does not match encoded bytes")
+	}
+	if _, err := os.Stat(output + ".scene.json"); err != nil {
+		t.Fatal(err)
+	}
+	streams := probeStreams(t, output)
+	if len(streams) != 2 || streams[0].CodecName != "h264" || streams[0].Width != 640 || streams[0].Height != 360 || streams[0].Frames != "24" || streams[1].CodecName != "aac" {
+		t.Fatalf("unexpected encoded streams: %+v", streams)
+	}
+	if _, err := renderer.Render(context.Background(), request, output); err == nil {
+		t.Fatal("overwrote an existing output")
+	}
+}
+
+func TestBrowserLosslessRGBMatchesCapturedPixels(t *testing.T) {
+	renderer, request := browserFixture(t, nil)
+	renderer.options.Lossless = true
+	renderer.options.X264Preset = "ultrafast"
+	renderer.options.EncoderThreads = 2
+	request.Config.DurationInFrames = 6
+	worker, err := renderer.newWorker(context.Background(), request)
+	if err != nil {
+		t.Fatal(err)
+	}
+	capture, err := worker.capture(context.Background(), 3)
+	worker.close()
+	if err != nil {
+		t.Fatal(err)
+	}
+	image, err := png.Decode(bytes.NewReader(capture))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := make([]byte, 0, request.Config.Width*request.Config.Height*3)
+	for y := 0; y < request.Config.Height; y++ {
+		for x := 0; x < request.Config.Width; x++ {
+			r, g, b, _ := image.At(x, y).RGBA()
+			want = append(want, byte(r>>8), byte(g>>8), byte(b>>8))
+		}
+	}
+	output := filepath.Join(t.TempDir(), "lossless.mp4")
+	result, err := renderer.Render(context.Background(), request, output)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := exec.Command(renderer.options.FFmpegExecutable, "-v", "error", "-i", output, "-vf", `select=eq(n\,3)`, "-frames:v", "1", "-pix_fmt", "rgb24", "-f", "rawvideo", "pipe:1").Output()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(want, got) {
+		if len(want) != len(got) {
+			t.Fatalf("lossless RGB byte count: want %d, got %d", len(want), len(got))
+		}
+		for i := range want {
+			if want[i] != got[i] {
+				t.Fatalf("lossless scene RGB differs at pixel %d,%d channel %d: want %d, got %d", i/3%request.Config.Width, i/3/request.Config.Width, i%3, want[i], got[i])
+			}
+		}
+	}
+	if result.Metrics.Workers != 2 || result.Metrics.CaptureAndEncode <= 0 || result.Metrics.SeekWorkerTime <= 0 {
+		t.Fatalf("missing stage measurements: %+v", result.Metrics)
+	}
+}
+
+func TestBrowserAlpha(t *testing.T) {
+	renderer, request := browserFixture(t, nil)
+	request.Config.Transparent = true
+	request.Config.DurationInFrames = 6
+	worker, err := renderer.newWorker(context.Background(), request)
+	if err != nil {
+		t.Fatal(err)
+	}
+	buffer, err := worker.capture(context.Background(), 3)
+	worker.close()
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertTransparentCorner(t, buffer)
+	output := filepath.Join(t.TempDir(), "overlay.webm")
+	result, err := renderer.Render(context.Background(), request, output)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.Transparent || result.Codec != VP9 {
+		t.Fatalf("invalid transparent result: %+v", result)
+	}
+	decoded, err := exec.Command(renderer.options.FFmpegExecutable, "-hide_banner", "-loglevel", "error", "-c:v", "libvpx-vp9", "-i", output, "-frames:v", "1", "-f", "image2pipe", "-vcodec", "png", "pipe:1").Output()
+	if err != nil {
+		t.Fatalf("decode transparent video: %v", err)
+	}
+	assertTransparentCorner(t, decoded)
+}
+
+func TestBrowserCancellationAndReuse(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancelled := false
+	renderer, request := browserFixture(t, func(progress Progress) {
+		if progress.WrittenFrames == 2 && !cancelled {
+			cancelled = true
+			cancel()
+		}
+	})
+	output := filepath.Join(t.TempDir(), "cancelled.mp4")
+	_, err := renderer.Render(ctx, request, output)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected cancellation, got %v", err)
+	}
+	for _, path := range []string{output, output + ".scene.json"} {
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("cancelled job published %s", path)
+		}
+	}
+	request.Config.DurationInFrames = 6
+	if _, err := renderer.Render(context.Background(), request, output); err != nil {
+		t.Fatalf("browser could not be reused after cancellation: %v", err)
+	}
+}
+
+func TestBrowserReportsSceneFailure(t *testing.T) {
+	renderer, request := browserFixture(t, nil)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.Write([]byte(`<script>window.__scene = { version: 1, ready: async () => { throw new Error('missing scene resource'); } };</script>`))
+	}))
+	defer server.Close()
+	request.URL = server.URL
+	_, err := renderer.Render(context.Background(), request, filepath.Join(t.TempDir(), "failed.mp4"))
+	if err == nil || !strings.Contains(err.Error(), "missing scene resource") {
+		t.Fatalf("lost scene error: %v", err)
+	}
+}
+
+func TestBrowserFrameTimeoutDoesNotPublishOutput(t *testing.T) {
+	renderer, request := browserFixture(t, nil)
+	renderer.options.FrameTimeout = time.Second
+	request.Config.DurationInFrames = 1
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.Write([]byte(`<script>window.__scene = { version: 1, manifest: window.__sceneRequest, ready: async () => {}, seek: () => new Promise(() => {}) };</script>`))
+	}))
+	defer server.Close()
+	request.URL = server.URL
+	output := filepath.Join(t.TempDir(), "timed-out.mp4")
+	_, err := renderer.Render(context.Background(), request, output)
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("expected frame deadline, got %v", err)
+	}
+	if _, err := os.Stat(output); !os.IsNotExist(err) {
+		t.Fatal("timed-out frame published an asset")
+	}
+}
+
+func assertTransparentCorner(t *testing.T, data []byte) {
+	t.Helper()
+	image, err := png.Decode(bytes.NewReader(data))
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, _, _, alpha := image.At(0, 0).RGBA()
+	if alpha != 0 {
+		t.Fatalf("expected alpha zero at empty corner, got %d", alpha)
+	}
+}
+
+type probeStream struct {
+	CodecName string `json:"codec_name"`
+	Width     int    `json:"width"`
+	Height    int    `json:"height"`
+	Frames    string `json:"nb_frames"`
+}
+
+func probeStreams(t *testing.T, path string) []probeStream {
+	t.Helper()
+	executable := os.Getenv("SCENE_FFPROBE")
+	if executable == "" {
+		t.Fatal("SCENE_FFPROBE is required for native verification")
+	}
+	data, err := exec.Command(executable, "-v", "error", "-show_streams", "-of", "json", path).Output()
+	if err != nil {
+		t.Fatalf("probe rendered output: %v", err)
+	}
+	var result struct {
+		Streams []probeStream `json:"streams"`
+	}
+	if err := json.Unmarshal(data, &result); err != nil {
+		t.Fatal(err)
+	}
+	return result.Streams
+}

package/renderer/cmd/scene-render/main.go

@@ -0,0 +1,128 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	sceneengine "github.com/catalinfl/machinal-scenes/renderer"
+)
+
+var version = "dev"
+
+type cliOptions struct {
+	printVersion   bool
+	requestFile    string
+	output         string
+	serveDirectory string
+	renderer       sceneengine.Options
+}
+
+func main() {
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	options := parseFlags()
+	if err := run(ctx, options, os.Stdout, os.Stderr); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func parseFlags() cliOptions {
+	var options cliOptions
+	var allowedOrigins string
+	flag.BoolVar(&options.printVersion, "version", false, "print the renderer version")
+	flag.StringVar(&options.requestFile, "request", "", "JSON/YAML job file (required)")
+	flag.StringVar(&options.output, "output", "", "new .mp4 or .webm output file (required)")
+	flag.StringVar(&options.serveDirectory, "serve", "", "serve a built scene directory on an ephemeral loopback port")
+	flag.StringVar(&options.renderer.BrowserExecutable, "browser", os.Getenv("SCENE_BROWSER"), "pinned Chrome Headless Shell executable")
+	flag.StringVar(&options.renderer.FFmpegExecutable, "ffmpeg", "ffmpeg", "FFmpeg executable")
+	flag.IntVar(&options.renderer.Concurrency, "workers", 2, "concurrent pages (1–16)")
+	flag.IntVar(&options.renderer.EncoderThreads, "encoder-threads", 0, "encoder threads (0 = automatic, at most 32)")
+	flag.StringVar(&options.renderer.X264Preset, "x264-preset", "medium", "x264 speed/compression preset (does not select quality)")
+	flag.BoolVar(&options.renderer.Lossless, "lossless", false, "lossless intermediate encoding; MP4 retains RGB, WebM retains alpha")
+	flag.BoolVar(&options.renderer.EnableGPU, "gpu", false, "allow hardware GPU rendering (requires working device access)")
+	flag.DurationVar(&options.renderer.FrameTimeout, "frame-timeout", 30*time.Second, "timeout for page preparation or one frame")
+	flag.BoolVar(&options.renderer.NoSandbox, "no-sandbox", false, "disable Chromium sandbox for an externally isolated container")
+	flag.StringVar(&allowedOrigins, "allow-origins", "", "comma-separated additional resource origins")
+	flag.Parse()
+	if allowedOrigins != "" {
+		for _, origin := range strings.Split(allowedOrigins, ",") {
+			options.renderer.AllowedOrigins = append(options.renderer.AllowedOrigins, strings.TrimSpace(origin))
+		}
+	}
+	return options
+}
+
+func run(ctx context.Context, options cliOptions, stdout, stderr io.Writer) error {
+	if options.printVersion {
+		if _, err := fmt.Fprintf(stdout, "machinal-scene-render %s\n", version); err != nil {
+			return fmt.Errorf("write renderer version: %w", err)
+		}
+		return nil
+	}
+	if options.requestFile == "" || options.output == "" {
+		return fmt.Errorf("-request and -output are required")
+	}
+	request, err := loadRequest(options.requestFile)
+	if err != nil {
+		return err
+	}
+	if options.serveDirectory != "" {
+		resolvedURL, closeServer, err := serveScene(options.serveDirectory, request.URL)
+		if err != nil {
+			return err
+		}
+		defer closeServer()
+		request.URL = resolvedURL
+	}
+	options.renderer.Progress = func(progress sceneengine.Progress) {
+		if progress.WrittenFrames == 1 || progress.WrittenFrames%30 == 0 || progress.WrittenFrames == progress.TotalFrames {
+			fmt.Fprintf(stderr, "frames %d/%d · %s\n", progress.WrittenFrames, progress.TotalFrames, progress.Elapsed.Round(time.Millisecond))
+		}
+	}
+	renderer, err := sceneengine.New(ctx, options.renderer)
+	if err != nil {
+		return err
+	}
+	defer renderer.Close()
+	result, err := renderer.Render(ctx, request, options.output)
+	if err != nil {
+		return err
+	}
+	if err := json.NewEncoder(stdout).Encode(result); err != nil {
+		return fmt.Errorf("write result JSON: %w", err)
+	}
+	return nil
+}
+
+func loadRequest(path string) (sceneengine.Request, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return sceneengine.Request{}, fmt.Errorf("open request: %w", err)
+	}
+	defer file.Close()
+	request, err := sceneengine.DecodeRequest(file)
+	if err != nil {
+		return request, err
+	}
+	for index := range request.Audio {
+		source := &request.Audio[index]
+		if !filepath.IsAbs(source.File) {
+			source.File = filepath.Join(filepath.Dir(path), source.File)
+		}
+		source.File, err = filepath.Abs(source.File)
+		if err != nil {
+			return request, fmt.Errorf("resolve audio[%d]: %w", index, err)
+		}
+	}
+	return request, nil
+}

package/renderer/cmd/scene-render/main_test.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestVersionDoesNotRequireRenderingTools(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := run(context.Background(), cliOptions{printVersion: true}, &stdout, &stderr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := stdout.String(), "machinal-scene-render "+version+"\n"; got != want {
+		t.Fatalf("version output = %q, want %q", got, want)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("unexpected diagnostics: %s", stderr.String())
+	}
+}
+
+func TestVersionReportsWriteFailure(t *testing.T) {
+	err := run(context.Background(), cliOptions{printVersion: true}, failingWriter{}, io.Discard)
+	if !errors.Is(err, io.ErrClosedPipe) || !strings.Contains(err.Error(), "write renderer version") {
+		t.Fatalf("expected a wrapped write error, got %v", err)
+	}
+}
+
+type failingWriter struct{}
+
+func (failingWriter) Write([]byte) (int, error) {
+	return 0, io.ErrClosedPipe
+}