@machinal/scenes 0.0.0-stage → 0.1.1

package/renderer/render.go

@@ -0,0 +1,141 @@
+package sceneengine
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Render publishes an asset only after its complete video/audio encoding succeeds.
+func (r *Renderer) Render(ctx context.Context, request Request, output string) (result Result, renderErr error) {
+	if err := request.Validate(); err != nil {
+		return Result{}, err
+	}
+	codec, err := outputCodec(output, request.Config.Transparent)
+	if err != nil {
+		return Result{}, err
+	}
+	select {
+	case r.lease <- struct{}{}:
+		defer func() { <-r.lease }()
+	default:
+		return Result{}, fmt.Errorf("renderer is busy")
+	}
+	defer func() { renderErr = r.browserLog.wrap(renderErr) }()
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	stop := context.AfterFunc(r.browser, cancel)
+	defer stop()
+	started := time.Now()
+	staged, err := stageOutput(output)
+	if err != nil {
+		return Result{}, err
+	}
+	defer os.Remove(staged)
+	workers, err := r.loadWorkers(ctx, request)
+	if err != nil {
+		return Result{}, err
+	}
+	defer closeWorkers(workers)
+	metrics := RenderMetrics{Workers: len(workers), Load: time.Since(started)}
+	process, err := startEncoder(ctx, r.options, request, codec, staged)
+	if err != nil {
+		return Result{}, err
+	}
+	captures := make([]captureFunc, len(workers))
+	for index, worker := range workers {
+		captures[index] = worker.capture
+	}
+	streamStarted := time.Now()
+	err = streamFrames(ctx, request.Config.DurationInFrames, captures, process.input, func(written int) {
+		if r.options.Progress != nil {
+			r.options.Progress(Progress{WrittenFrames: written, TotalFrames: request.Config.DurationInFrames, Elapsed: time.Since(started)})
+		}
+	})
+	metrics.CaptureAndEncode = time.Since(streamStarted)
+	if err != nil {
+		cancel()
+		encodingErr := process.finish()
+		if encodingErr != nil {
+			return Result{}, fmt.Errorf("%w; encoder: %v", err, encodingErr)
+		}
+		return Result{}, err
+	}
+	drainStarted := time.Now()
+	if err := process.finish(); err != nil {
+		return Result{}, err
+	}
+	metrics.EncoderDrain = time.Since(drainStarted)
+	for _, worker := range workers {
+		metrics.SeekWorkerTime += worker.seekTime
+		metrics.CaptureWorkerTime += worker.captureTime
+	}
+	if err := ctx.Err(); err != nil {
+		return Result{}, err
+	}
+	return publishOutput(staged, output, request, workers[0].manifest, codec, time.Since(started), metrics)
+}
+
+func outputCodec(output string, transparent bool) (Codec, error) {
+	switch strings.ToLower(filepath.Ext(output)) {
+	case ".mp4":
+		if transparent {
+			return "", fmt.Errorf("transparent output requires .webm (VP9), not MP4")
+		}
+		return H264, nil
+	case ".webm":
+		return VP9, nil
+	default:
+		return "", fmt.Errorf("output extension must be .mp4 or .webm")
+	}
+}
+
+func (r *Renderer) loadWorkers(ctx context.Context, request Request) ([]*frameWorker, error) {
+	count := min(r.options.Concurrency, request.Config.DurationInFrames)
+	workers := make([]*frameWorker, count)
+	loadCtx, cancel := context.WithCancelCause(ctx)
+	var loading sync.WaitGroup
+	for index := range count {
+		loading.Go(func() {
+			worker, err := r.newWorker(loadCtx, request)
+			if err != nil {
+				cancel(fmt.Errorf("initialize worker %d: %w", index, err))
+				return
+			}
+			workers[index] = worker
+		})
+	}
+	loading.Wait()
+	if err := context.Cause(loadCtx); err != nil {
+		closeWorkers(workers)
+		cancel(err)
+		return nil, err
+	}
+	for _, worker := range workers[1:] {
+		if !reflect.DeepEqual(worker.manifest, workers[0].manifest) {
+			closeWorkers(workers)
+			cancel(context.Canceled)
+			return nil, fmt.Errorf("scene manifests differ between workers")
+		}
+	}
+	// Keep successful tabs alive until the job releases its workers.
+	closeFirst := workers[0].close
+	workers[0].close = func() {
+		cancel(context.Canceled)
+		closeFirst()
+	}
+	return workers, nil
+}
+
+func closeWorkers(workers []*frameWorker) {
+	for _, worker := range workers {
+		if worker != nil {
+			worker.close()
+		}
+	}
+}

package/renderer/request.go

@@ -0,0 +1,140 @@
+package sceneengine
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/url"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	// Embedded originals: four 5 MiB images and two 20 MiB videos plus base64 expansion.
+	MaxRequestBytes    = 96 << 20
+	maxDimension       = 8192
+	maxFPS             = 240
+	maxFrames          = 1_000_000
+	maxAudioTracks     = 64
+	maxVolume          = 4
+	maxDurationSeconds = 24 * 60 * 60
+)
+
+// DecodeRequest rejects unknown fields, trailing documents and oversized input.
+func DecodeRequest(reader io.Reader) (Request, error) {
+	data, err := io.ReadAll(io.LimitReader(reader, MaxRequestBytes+1))
+	if err != nil {
+		return Request{}, fmt.Errorf("read scene request: %w", err)
+	}
+	if len(data) > MaxRequestBytes {
+		return Request{}, fmt.Errorf("scene request exceeds %d bytes", MaxRequestBytes)
+	}
+	var request Request
+	if bytes.HasPrefix(bytes.TrimSpace(data), []byte("{")) {
+		decoder := json.NewDecoder(bytes.NewReader(data))
+		decoder.DisallowUnknownFields()
+		if err := decoder.Decode(&request); err != nil {
+			return request, fmt.Errorf("decode scene JSON: %w", err)
+		}
+		if err := decoder.Decode(new(any)); err != io.EOF {
+			return request, fmt.Errorf("scene JSON must contain one document")
+		}
+	} else {
+		decoder := yaml.NewDecoder(bytes.NewReader(data))
+		decoder.KnownFields(true)
+		if err := decoder.Decode(&request); err != nil {
+			return request, fmt.Errorf("decode scene YAML: %w", err)
+		}
+		if err := decoder.Decode(new(any)); err != io.EOF {
+			return request, fmt.Errorf("scene YAML must contain one document")
+		}
+	}
+	if _, err := request.browserPayload(); err != nil {
+		return request, fmt.Errorf("props must contain JSON-compatible values: %w", err)
+	}
+	return request, nil
+}
+
+func (r Request) Validate() error {
+	if r.Version != ProtocolVersion {
+		return fmt.Errorf("unsupported scene protocol version %d", r.Version)
+	}
+	if strings.TrimSpace(r.SceneID) == "" {
+		return fmt.Errorf("sceneId is required")
+	}
+	if _, err := parseOrigin(r.URL); err != nil {
+		return fmt.Errorf("scene URL: %w", err)
+	}
+	if err := r.Config.validate(); err != nil {
+		return err
+	}
+	if len(r.Audio) > maxAudioTracks {
+		return fmt.Errorf("at most %d audio tracks are supported", maxAudioTracks)
+	}
+	for index, track := range r.Audio {
+		if err := track.validate(r.Config.Duration()); err != nil {
+			return fmt.Errorf("audio[%d]: %w", index, err)
+		}
+	}
+	if _, err := r.browserPayload(); err != nil {
+		return fmt.Errorf("serialize scene props: %w", err)
+	}
+	return nil
+}
+
+func (c Config) validate() error {
+	if c.Width <= 0 || c.Height <= 0 || c.Width > maxDimension || c.Height > maxDimension {
+		return fmt.Errorf("width and height must be between 1 and %d", maxDimension)
+	}
+	if c.Width%2 != 0 || c.Height%2 != 0 {
+		return fmt.Errorf("video width and height must be even")
+	}
+	if !finite(c.FPS) || c.FPS <= 0 || c.FPS > maxFPS {
+		return fmt.Errorf("fps must be between 0 and %d", maxFPS)
+	}
+	if c.DurationInFrames <= 0 || c.DurationInFrames > maxFrames {
+		return fmt.Errorf("durationInFrames must be between 1 and %d", maxFrames)
+	}
+	if !finite(c.Duration()) || c.Duration() > maxDurationSeconds {
+		return fmt.Errorf("scene duration must not exceed %d seconds", maxDurationSeconds)
+	}
+	if !finite(c.CaptionSafeBottom) || c.CaptionSafeBottom < 0 || c.CaptionSafeBottom > 0.5 {
+		return fmt.Errorf("captionSafeBottom must be between 0 and 0.5")
+	}
+	return nil
+}
+
+func (a AudioTrack) validate(totalDuration float64) error {
+	if strings.TrimSpace(a.File) == "" {
+		return fmt.Errorf("file is required")
+	}
+	if !finite(a.Start) || a.Start < 0 || a.Start >= totalDuration {
+		return fmt.Errorf("start must fall inside the composition")
+	}
+	if !finite(a.From) || a.From < 0 {
+		return fmt.Errorf("from must be nonnegative")
+	}
+	if !finite(a.Duration) || a.Duration <= 0 {
+		return fmt.Errorf("duration must be positive")
+	}
+	if a.Volume != nil && (!finite(*a.Volume) || *a.Volume < 0 || *a.Volume > maxVolume) {
+		return fmt.Errorf("volume must be between 0 and %d", maxVolume)
+	}
+	return nil
+}
+
+func finite(value float64) bool { return !math.IsNaN(value) && !math.IsInf(value, 0) }
+
+func parseOrigin(raw string) (string, error) {
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		return "", err
+	}
+	if (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" || parsed.User != nil {
+		return "", fmt.Errorf("expected an absolute HTTP(S) URL without credentials")
+	}
+	return strings.ToLower(parsed.Scheme + "://" + parsed.Host), nil
+}

package/renderer/request_test.go

@@ -0,0 +1,94 @@
+package sceneengine
+
+import (
+	"math"
+	"strings"
+	"testing"
+)
+
+func fixtureRequest() Request {
+	return Request{Version: 1, URL: "http://127.0.0.1:5178/scene.html", SceneID: "intro", Config: Config{Width: 640, Height: 360, FPS: 30, DurationInFrames: 90}}
+}
+
+func TestDecodeRequestRejectsAmbiguousInput(t *testing.T) {
+	for _, input := range []string{
+		`{"version":1,"unexpected":true}`,
+		`{"version":1} {"version":1}`,
+		"version: 1\n---\nversion: 1",
+		"version: 1\nversion: 2",
+		"version: 1\nunexpected: true",
+	} {
+		if _, err := DecodeRequest(strings.NewReader(input)); err == nil {
+			t.Errorf("accepted ambiguous request %q", input)
+		}
+	}
+}
+
+func TestDecodeYAMLPropsAreJSONCompatible(t *testing.T) {
+	request, err := DecodeRequest(strings.NewReader("version: 1\nprops:\n  title: Example\n  items: [1, two]\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := request.browserPayload(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRequestValidation(t *testing.T) {
+	cases := map[string]func(*Request){
+		"odd dimensions":       func(r *Request) { r.Config.Width = 641 },
+		"invalid fps":          func(r *Request) { r.Config.FPS = math.NaN() },
+		"overflow duration":    func(r *Request) { r.Config.FPS = math.SmallestNonzeroFloat64 },
+		"empty duration":       func(r *Request) { r.Config.DurationInFrames = 0 },
+		"file URL":             func(r *Request) { r.URL = "file:///secret" },
+		"credentials":          func(r *Request) { r.URL = "https://user:pass@example.com" },
+		"invalid audio":        func(r *Request) { r.Audio = []AudioTrack{{File: "a.wav", Start: -1, Duration: 1}} },
+		"invalid caption band": func(r *Request) { r.Config.CaptionSafeBottom = 0.7 },
+	}
+	for name, mutate := range cases {
+		t.Run(name, func(t *testing.T) {
+			request := fixtureRequest()
+			mutate(&request)
+			if err := request.Validate(); err == nil {
+				t.Fatal("accepted invalid request")
+			}
+		})
+	}
+	if err := fixtureRequest().Validate(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestCaptionSafeBandSurvivesYAMLAndBrowserPayload(t *testing.T) {
+	request, err := DecodeRequest(strings.NewReader("version: 1\nconfig:\n  width: 1920\n  height: 1080\n  fps: 30\n  durationInFrames: 30\n  captionSafeBottom: 0.24\n"))
+	if err != nil || request.Config.CaptionSafeBottom != 0.24 {
+		t.Fatal(request, err)
+	}
+	payload, err := request.browserPayload()
+	if err != nil || !strings.Contains(string(payload), `"captionSafeBottom":0.24`) {
+		t.Fatal(string(payload), err)
+	}
+}
+
+func TestResourceOrigins(t *testing.T) {
+	allowed := map[string]bool{"http://127.0.0.1:5178": true}
+	for _, request := range []string{"http://127.0.0.1:5178/font.woff2", "data:image/png;base64,AA==", "blob:http://127.0.0.1:5178/id"} {
+		if !allowRequest(request, allowed) {
+			t.Errorf("blocked %s", request)
+		}
+	}
+	for _, request := range []string{"http://127.0.0.1:8080/private", "file:///secret", "https://example.com/font.woff2", "http://127.0.0.1:5178@evil.test"} {
+		if allowRequest(request, allowed) {
+			t.Errorf("allowed %s", request)
+		}
+	}
+}
+
+func TestAlphaRequiresWebM(t *testing.T) {
+	if _, err := outputCodec("scene.mp4", true); err == nil {
+		t.Fatal("accepted alpha MP4")
+	}
+	if codec, err := outputCodec("scene.webm", true); err != nil || codec != VP9 {
+		t.Fatalf("expected VP9, got %s, %v", codec, err)
+	}
+}

package/renderer/types.go

@@ -0,0 +1,113 @@
+package sceneengine
+
+import (
+	"encoding/json"
+	"time"
+)
+
+const ProtocolVersion = 1
+
+// Config uses frame indexes for duration and seconds only for FPS conversion.
+type Config struct {
+	Width             int     `json:"width" yaml:"width"`
+	Height            int     `json:"height" yaml:"height"`
+	FPS               float64 `json:"fps" yaml:"fps"`
+	DurationInFrames  int     `json:"durationInFrames" yaml:"durationInFrames"`
+	Transparent       bool    `json:"transparent,omitempty" yaml:"transparent,omitempty"`
+	CaptionSafeBottom float64 `json:"captionSafeBottom,omitempty" yaml:"captionSafeBottom,omitempty"`
+}
+
+func (c Config) Duration() float64 { return float64(c.DurationInFrames) / c.FPS }
+
+// AudioTrack describes a local source; the scene's browser never plays this audio.
+type AudioTrack struct {
+	File     string   `json:"file" yaml:"file"`
+	Start    float64  `json:"start" yaml:"start"`
+	From     float64  `json:"from,omitempty" yaml:"from,omitempty"`
+	Duration float64  `json:"duration" yaml:"duration"`
+	Volume   *float64 `json:"volume,omitempty" yaml:"volume,omitempty"`
+}
+
+// Request is a portable JSON/YAML render job. Relative audio paths are resolved by the CLI.
+type Request struct {
+	Version int            `json:"version" yaml:"version"`
+	URL     string         `json:"url" yaml:"url"`
+	SceneID string         `json:"sceneId" yaml:"sceneId"`
+	Seed    string         `json:"seed,omitempty" yaml:"seed,omitempty"`
+	Config  Config         `json:"config" yaml:"config"`
+	Props   map[string]any `json:"props,omitempty" yaml:"props,omitempty"`
+	Audio   []AudioTrack   `json:"audio,omitempty" yaml:"audio,omitempty"`
+}
+
+// Manifest records the resolved scene parameters reported by the browser runtime.
+type Manifest struct {
+	Version int            `json:"version"`
+	SceneID string         `json:"sceneId"`
+	Seed    string         `json:"seed"`
+	Config  Config         `json:"config"`
+	Props   map[string]any `json:"props"`
+}
+
+type Codec string
+
+const (
+	H264 Codec = "h264"
+	VP9  Codec = "vp9"
+)
+
+// Result is the asset boundary between this module and an application.
+type Result struct {
+	Version     int           `json:"version"`
+	File        string        `json:"file"`
+	SHA256      string        `json:"sha256"`
+	Size        int64         `json:"size"`
+	Duration    float64       `json:"duration"`
+	Width       int           `json:"width"`
+	Height      int           `json:"height"`
+	FPS         float64       `json:"fps"`
+	Frames      int           `json:"frames"`
+	HasAudio    bool          `json:"hasAudio"`
+	Transparent bool          `json:"transparent"`
+	Codec       Codec         `json:"codec"`
+	Scene       Manifest      `json:"scene"`
+	Elapsed     time.Duration `json:"elapsedNanoseconds"`
+	Metrics     RenderMetrics `json:"metrics"`
+}
+
+type RenderMetrics struct {
+	Workers           int           `json:"workers"`
+	Load              time.Duration `json:"loadNanoseconds"`
+	CaptureAndEncode  time.Duration `json:"captureAndEncodeNanoseconds"`
+	EncoderDrain      time.Duration `json:"encoderDrainNanoseconds"`
+	SeekWorkerTime    time.Duration `json:"seekWorkerNanoseconds"`
+	CaptureWorkerTime time.Duration `json:"captureWorkerNanoseconds"`
+}
+
+type Progress struct {
+	WrittenFrames int           `json:"writtenFrames"`
+	TotalFrames   int           `json:"totalFrames"`
+	Elapsed       time.Duration `json:"elapsedNanoseconds"`
+}
+
+// Options configures browser ownership and the bounded frame pipeline.
+type Options struct {
+	BrowserExecutable string
+	FFmpegExecutable  string
+	Concurrency       int
+	FrameTimeout      time.Duration
+	AllowedOrigins    []string
+	NoSandbox         bool
+	EnableGPU         bool
+	Lossless          bool
+	X264Preset        string
+	EncoderThreads    int
+	Progress          func(Progress)
+}
+
+func (r Request) browserPayload() ([]byte, error) {
+	props := r.Props
+	if props == nil {
+		props = map[string]any{}
+	}
+	return json.Marshal(Manifest{Version: r.Version, SceneID: r.SceneID, Seed: r.Seed, Config: r.Config, Props: props})
+}

package/renderer/worker.go

@@ -0,0 +1,110 @@
+package sceneengine
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/chromedp/cdproto/cdp"
+	"github.com/chromedp/cdproto/emulation"
+	"github.com/chromedp/cdproto/page"
+	"github.com/chromedp/chromedp"
+)
+
+type frameWorker struct {
+	ctx         context.Context
+	close       func()
+	request     Request
+	manifest    Manifest
+	options     Options
+	cancel      context.CancelFunc
+	seekTime    time.Duration
+	captureTime time.Duration
+}
+
+func (r *Renderer) newWorker(job context.Context, request Request) (*frameWorker, error) {
+	tab, cancel := chromedp.NewContext(r.browser)
+	stop := context.AfterFunc(job, cancel)
+	worker := &frameWorker{ctx: tab, close: func() { stop(); cancel() }, cancel: cancel, request: request, options: r.options}
+	// The first action owns the target's event loop, so it must use the tab's
+	// lifetime context rather than the short-lived page preparation context.
+	timeout := time.AfterFunc(r.options.FrameTimeout, cancel)
+	err := chromedp.Do(tab)
+	timeout.Stop()
+	if err != nil {
+		worker.close()
+		return nil, fmt.Errorf("create worker tab: %w", err)
+	}
+	if err := worker.load(); err != nil {
+		worker.close()
+		return nil, err
+	}
+	return worker, nil
+}
+
+func (w *frameWorker) load() error {
+	payload, err := w.request.browserPayload()
+	if err != nil {
+		return fmt.Errorf("serialize browser request: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(w.ctx, w.options.FrameTimeout)
+	defer cancel()
+	err = chromedp.Do(ctx,
+		chromedp.EmulateViewport(int64(w.request.Config.Width), int64(w.request.Config.Height)),
+		chromedp.Func(func(ctx context.Context, target *chromedp.Target) error {
+			if !w.request.Config.Transparent {
+				return nil
+			}
+			// Explicit zero alpha is omitted by the generated protocol type.
+			return target.Call(ctx, emulation.SetDefaultBackgroundColorOverride.Method, map[string]any{"color": map[string]any{"r": 0, "g": 0, "b": 0, "a": 0}}, nil)
+		}),
+		restrictNetwork(w.ctx, w.request.URL, w.options.AllowedOrigins, w.cancel),
+		chromedp.Func(func(ctx context.Context, target *chromedp.Target) error {
+			_, err := cdp.Call(ctx, target, page.AddScriptToEvaluateOnNewDocument, page.AddScriptToEvaluateOnNewDocumentParams{Source: "window.__sceneRequest = " + string(payload) + ";"})
+			return err
+		}),
+		chromedp.Navigate(w.request.URL),
+		chromedp.Poll[chromedp.Void]("Boolean(window.__scene || window.__sceneError)", chromedp.WithPollingTimeout(w.options.FrameTimeout)),
+	)
+	if err != nil {
+		return fmt.Errorf("prepare scene page: %w", err)
+	}
+	w.manifest, err = chromedp.Run(ctx, chromedp.Evaluate[Manifest](`(async () => {
+   if (window.__sceneError) throw new Error(window.__sceneError);
+   if (window.__scene.version !== 1) throw new Error('Unsupported scene protocol');
+   await window.__scene.ready();
+   return window.__scene.manifest;
+  })()`, chromedp.EvalAwaitPromise))
+	if err != nil {
+		return fmt.Errorf("load scene %q: %w", w.request.SceneID, err)
+	}
+	if w.manifest.Version != ProtocolVersion || w.manifest.SceneID != w.request.SceneID || w.manifest.Config != w.request.Config {
+		return fmt.Errorf("scene manifest does not match the render request")
+	}
+	return nil
+}
+
+func (w *frameWorker) capture(job context.Context, frame int) ([]byte, error) {
+	ctx, cancel := context.WithTimeout(w.ctx, w.options.FrameTimeout)
+	defer cancel()
+	stop := context.AfterFunc(job, cancel)
+	defer stop()
+	started := time.Now()
+	err := chromedp.Do(ctx, chromedp.Evaluate[chromedp.Void](fmt.Sprintf("window.__scene.seek(%d)", frame), chromedp.EvalAwaitPromise))
+	w.seekTime += time.Since(started)
+	if err != nil {
+		return nil, fmt.Errorf("seek frame %d: %w", frame, err)
+	}
+	started = time.Now()
+	buffer, err := chromedp.Run(ctx, func(ctx context.Context, target *chromedp.Target) ([]byte, error) {
+		beyondViewport, optimize := false, true
+		params := page.CaptureScreenshotParams{Format: page.CaptureScreenshotFormatPng, CaptureBeyondViewport: &beyondViewport, OptimizeForSpeed: &optimize}
+		result, err := cdp.Call(ctx, target, page.CaptureScreenshot, params)
+		return result.Data, err
+	})
+	w.captureTime += time.Since(started)
+	if err != nil {
+		return nil, fmt.Errorf("capture frame %d: %w", frame, err)
+	}
+	return buffer, nil
+}