@machinal/scenes 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"time"
+)
+
+func serveScene(directory, sceneURL string) (string, func(), error) {
+	info, err := os.Stat(directory)
+	if err != nil || !info.IsDir() {
+		return "", nil, fmt.Errorf("scene build directory is unavailable: %s", directory)
+	}
+	relative, err := url.Parse(sceneURL)
+	if err != nil || relative.IsAbs() || relative.Host != "" {
+		return "", nil, fmt.Errorf("with -serve, request URL must be a relative scene path")
+	}
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return "", nil, fmt.Errorf("listen for scene files: %w", err)
+	}
+	server := &http.Server{Handler: http.FileServer(http.Dir(directory)), ReadHeaderTimeout: 5 * time.Second}
+	go func() {
+		// Shutdown below is the expected termination path for this private file server.
+		if err := server.Serve(listener); err != nil && err != http.ErrServerClosed {
+			server.Close()
+		}
+	}()
+	base := &url.URL{Scheme: "http", Host: listener.Addr().String(), Path: "/"}
+	closeServer := func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := server.Shutdown(ctx); err != nil {
+			server.Close()
+		}
+	}
+	return base.ResolveReference(relative).String(), closeServer, nil
+}

package/renderer/encoder.go

@@ -0,0 +1,116 @@
+package sceneengine
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"os/exec"
+	"strconv"
+	"strings"
+)
+
+const maxEncoderLogBytes = 32 << 10
+
+type encoder struct {
+	command *exec.Cmd
+	input   io.WriteCloser
+	log     tailLog
+}
+
+type tailLog struct{ buffer []byte }
+
+func (l *tailLog) Write(data []byte) (int, error) {
+	count := len(data)
+	l.buffer = append(l.buffer, data...)
+	if len(l.buffer) > maxEncoderLogBytes {
+		l.buffer = bytes.Clone(l.buffer[len(l.buffer)-maxEncoderLogBytes:])
+	}
+	return count, nil
+}
+
+func startEncoder(ctx context.Context, options Options, request Request, codec Codec, output string) (*encoder, error) {
+	args := encoderArgs(request, codec, output, options)
+	process := &encoder{command: exec.CommandContext(ctx, options.FFmpegExecutable, args...)}
+	process.command.Stderr = &process.log
+	input, err := process.command.StdinPipe()
+	if err != nil {
+		return nil, fmt.Errorf("open encoder stdin: %w", err)
+	}
+	process.input = input
+	if err := process.command.Start(); err != nil {
+		input.Close()
+		return nil, fmt.Errorf("start FFmpeg: %w", err)
+	}
+	return process, nil
+}
+
+func (e *encoder) finish() error {
+	closeErr := e.input.Close()
+	if err := e.command.Wait(); err != nil {
+		return fmt.Errorf("FFmpeg encoding failed: %w\n%s", err, string(e.log.buffer))
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close encoder input: %w", closeErr)
+	}
+	return nil
+}
+
+func encoderArgs(request Request, codec Codec, output string, options Options) []string {
+	args := []string{"-hide_banner", "-loglevel", "error", "-y", "-f", "image2pipe", "-framerate", decimal(request.Config.FPS), "-vcodec", "png", "-i", "pipe:0"}
+	for _, audio := range request.Audio {
+		args = append(args, "-i", audio.File)
+	}
+	if len(request.Audio) > 0 {
+		args = append(args, "-filter_complex", audioFilter(request), "-map", "0:v:0", "-map", "[audio]")
+		if codec == H264 {
+			args = append(args, "-c:a", "aac", "-b:a", "192k")
+		} else {
+			args = append(args, "-c:a", "libopus", "-b:a", "192k")
+		}
+	} else {
+		args = append(args, "-map", "0:v:0", "-an")
+	}
+	if codec == H264 {
+		encoder, crf, pixelFormat := "libx264", "18", "yuv420p"
+		if options.Lossless {
+			encoder, crf, pixelFormat = "libx264rgb", "0", "rgb24"
+		}
+		args = append(args, "-c:v", encoder, "-preset", options.X264Preset, "-crf", crf, "-pix_fmt", pixelFormat, "-movflags", "+faststart")
+	} else {
+		pixelFormat := "yuv420p"
+		if request.Config.Transparent {
+			pixelFormat = "yuva420p"
+		}
+		crf := "30"
+		if options.Lossless {
+			crf = "0"
+		}
+		args = append(args, "-c:v", "libvpx-vp9", "-crf", crf, "-b:v", "0", "-pix_fmt", pixelFormat, "-auto-alt-ref", "0")
+		if options.Lossless {
+			args = append(args, "-lossless", "1", "-deadline", "good", "-cpu-used", "4", "-row-mt", "1")
+		}
+	}
+	if options.EncoderThreads > 0 {
+		args = append(args, "-threads", strconv.Itoa(options.EncoderThreads))
+	}
+	return append(args, "-t", decimal(request.Config.Duration()), output)
+}
+
+func audioFilter(request Request) string {
+	filters := make([]string, 0, len(request.Audio)+1)
+	labels := make([]string, 0, len(request.Audio))
+	for index, track := range request.Audio {
+		volume := 1.0
+		if track.Volume != nil {
+			volume = *track.Volume
+		}
+		label := fmt.Sprintf("[a%d]", index)
+		filters = append(filters, fmt.Sprintf("[%d:a:0]atrim=start=%s:duration=%s,asetpts=PTS-STARTPTS,volume=%s,adelay=%d:all=1%s", index+1, decimal(track.From), decimal(track.Duration), decimal(volume), int64(track.Start*1000+0.5), label))
+		labels = append(labels, label)
+	}
+	filters = append(filters, fmt.Sprintf("%samix=inputs=%d:normalize=0,apad,atrim=duration=%s[audio]", strings.Join(labels, ""), len(labels), decimal(request.Config.Duration())))
+	return strings.Join(filters, ";")
+}
+
+func decimal(value float64) string { return strconv.FormatFloat(value, 'f', -1, 64) }

package/renderer/encoder_test.go

@@ -0,0 +1,22 @@
+package sceneengine
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLosslessEncodingRetainsCaptureDetail(t *testing.T) {
+	request := fixtureRequest()
+	options := Options{Lossless: true, X264Preset: "ultrafast", EncoderThreads: 2}
+	args := strings.Join(encoderArgs(request, H264, "scene.mp4", options), " ")
+	for _, want := range []string{"-vcodec png", "-c:v libx264rgb", "-preset ultrafast", "-crf 0", "-pix_fmt rgb24", "-threads 2"} {
+		if !strings.Contains(args, want) {
+			t.Fatalf("missing %s in %s", want, args)
+		}
+	}
+	request.Config.Transparent = true
+	args = strings.Join(encoderArgs(request, VP9, "scene.webm", options), " ")
+	if !strings.Contains(args, "-lossless 1") || !strings.Contains(args, "-pix_fmt yuva420p") {
+		t.Fatal(args)
+	}
+}

package/renderer/go.mod

@@ -0,0 +1,11 @@
+module github.com/catalinfl/machinal-scenes/renderer
+
+go 1.27.2
+
+require (
+	github.com/chromedp/cdproto v0.157.8
+	github.com/chromedp/chromedp v0.20.1
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require github.com/go-json-experiment/json v0.0.0-20260213210345-44df1a37e875 // indirect

package/renderer/go.sum

@@ -0,0 +1,10 @@
+github.com/chromedp/cdproto v0.157.8 h1:Tkq0AjsUlC3Z4sJfHBzV/uAAxnTF/AZyuSTjfV/1gvk=
+github.com/chromedp/cdproto v0.157.8/go.mod h1:h68JaIuFr9o3yiayxEYhBdvaxgYO3shDrPSYhNlyfu0=
+github.com/chromedp/chromedp v0.20.1 h1:983T9wmyM09JtROWlxhLQwljKOQovqt8CVE89W3U0NA=
+github.com/chromedp/chromedp v0.20.1/go.mod h1:6z1Y5FdKUxRzxx2qcC5h1xjaBJrSWrZp1mjgITfNZig=
+github.com/go-json-experiment/json v0.0.0-20260213210345-44df1a37e875 h1:XGPtjxqp0FS8jj1Z7QGcSOSgyq1fUPjNyJXvi3KfI4A=
+github.com/go-json-experiment/json v0.0.0-20260213210345-44df1a37e875/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package/renderer/network.go

@@ -0,0 +1,50 @@
+package sceneengine
+
+import (
+	"context"
+	"strings"
+
+	"github.com/chromedp/cdproto/cdp"
+	"github.com/chromedp/cdproto/fetch"
+	"github.com/chromedp/cdproto/network"
+	"github.com/chromedp/chromedp"
+)
+
+func allowRequest(raw string, allowed map[string]bool) bool {
+	if strings.HasPrefix(raw, "data:") || strings.HasPrefix(raw, "blob:") || raw == "about:blank" {
+		return true
+	}
+	origin, err := parseOrigin(raw)
+	return err == nil && allowed[origin]
+}
+
+func restrictNetwork(owner context.Context, requestURL string, extraOrigins []string, cancel context.CancelFunc) chromedp.Action[chromedp.Void] {
+	allowed := make(map[string]bool)
+	origin, _ := parseOrigin(requestURL)
+	allowed[origin] = true
+	for _, raw := range extraOrigins {
+		origin, _ := parseOrigin(raw)
+		allowed[origin] = true
+	}
+	return chromedp.Func(func(ctx context.Context, target *chromedp.Target) error {
+		events := cdp.Events(owner, target, fetch.RequestPaused)
+		go func() {
+			for request, err := range events {
+				if err != nil {
+					return
+				}
+				if allowRequest(request.Request.URL, allowed) {
+					_, err = cdp.Call(owner, target, fetch.ContinueRequest, fetch.ContinueRequestParams{RequestID: request.RequestID})
+				} else {
+					_, err = cdp.Call(owner, target, fetch.FailRequest, fetch.FailRequestParams{RequestID: request.RequestID, ErrorReason: network.ErrorReasonBlockedByClient})
+				}
+				if err != nil {
+					cancel()
+					return
+				}
+			}
+		}()
+		_, err := cdp.Call(ctx, target, fetch.Enable, fetch.EnableParams{})
+		return err
+	})
+}

package/renderer/output.go

@@ -0,0 +1,93 @@
+package sceneengine
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+func stageOutput(output string) (string, error) {
+	if _, err := os.Stat(output); err == nil {
+		return "", fmt.Errorf("output already exists: %s", output)
+	} else if !os.IsNotExist(err) {
+		return "", fmt.Errorf("inspect output: %w", err)
+	}
+	if _, err := os.Stat(output + ".scene.json"); err == nil {
+		return "", fmt.Errorf("asset manifest already exists: %s.scene.json", output)
+	} else if !os.IsNotExist(err) {
+		return "", fmt.Errorf("inspect asset manifest: %w", err)
+	}
+	staged, err := os.CreateTemp(filepath.Dir(output), ".scene-*"+filepath.Ext(output))
+	if err != nil {
+		return "", fmt.Errorf("stage video output: %w", err)
+	}
+	if err := staged.Close(); err != nil {
+		os.Remove(staged.Name())
+		return "", fmt.Errorf("close staged output: %w", err)
+	}
+	return staged.Name(), nil
+}
+
+func publishOutput(staged, output string, request Request, manifest Manifest, codec Codec, elapsed time.Duration, metrics RenderMetrics) (Result, error) {
+	hash, size, err := fingerprint(staged)
+	if err != nil {
+		return Result{}, err
+	}
+	absolute, err := filepath.Abs(output)
+	if err != nil {
+		return Result{}, fmt.Errorf("resolve output path: %w", err)
+	}
+	result := Result{Version: ProtocolVersion, File: absolute, SHA256: hash, Size: size, Duration: request.Config.Duration(), Width: request.Config.Width, Height: request.Config.Height, FPS: request.Config.FPS, Frames: request.Config.DurationInFrames, HasAudio: len(request.Audio) > 0, Transparent: request.Config.Transparent, Codec: codec, Scene: manifest, Elapsed: elapsed}
+	result.Metrics = metrics
+	data, err := json.MarshalIndent(result, "", "  ")
+	if err != nil {
+		return Result{}, fmt.Errorf("encode asset manifest: %w", err)
+	}
+	// A same-directory hard link publishes complete bytes without replacing an
+	// existing asset if another process claimed the destination during rendering.
+	if err := os.Link(staged, output); err != nil {
+		return Result{}, fmt.Errorf("publish video asset: %w", err)
+	}
+	if err := writeExclusive(output+".scene.json", data); err != nil {
+		os.Remove(output)
+		return Result{}, err
+	}
+	return result, nil
+}
+
+func fingerprint(path string) (string, int64, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return "", 0, fmt.Errorf("open rendered asset: %w", err)
+	}
+	defer file.Close()
+	hash := sha256.New()
+	size, err := io.Copy(hash, file)
+	if err != nil {
+		return "", 0, fmt.Errorf("fingerprint rendered asset: %w", err)
+	}
+	return hex.EncodeToString(hash.Sum(nil)), size, nil
+}
+
+func writeExclusive(path string, data []byte) error {
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0644)
+	if err != nil {
+		return fmt.Errorf("create asset manifest: %w", err)
+	}
+	_, writeErr := file.Write(data)
+	closeErr := file.Close()
+	if writeErr != nil {
+		os.Remove(path)
+		return fmt.Errorf("write asset manifest: %w", writeErr)
+	}
+	if closeErr != nil {
+		os.Remove(path)
+		return fmt.Errorf("close asset manifest: %w", closeErr)
+	}
+	return nil
+}

package/renderer/pipeline.go

@@ -0,0 +1,108 @@
+package sceneengine
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"sync"
+)
+
+type captureFunc func(ctx context.Context, frame int) ([]byte, error)
+
+type capturedFrame struct {
+	index int
+	bytes []byte
+	err   error
+}
+
+// Credits are returned only after ordered writes, bounding out-of-order buffers
+// even when an early frame is substantially slower than every later frame.
+func streamFrames(ctx context.Context, count int, captures []captureFunc, writer io.Writer, progress func(int)) error {
+	ctx, cancel := context.WithCancelCause(ctx)
+	defer cancel(nil)
+	window := len(captures) * 2
+	credits := make(chan struct{}, window)
+	jobs := make(chan int)
+	results := make(chan capturedFrame, len(captures))
+	var workers sync.WaitGroup
+	workers.Add(len(captures) + 1)
+	go scheduleFrames(ctx, count, credits, jobs, &workers)
+	for _, capture := range captures {
+		go captureFrames(ctx, capture, jobs, results, &workers)
+	}
+	defer workers.Wait()
+	defer cancel(context.Canceled)
+	pending := make(map[int][]byte)
+	next := 0
+	for next < count {
+		select {
+		case <-ctx.Done():
+			return context.Cause(ctx)
+		case result := <-results:
+			if result.err != nil {
+				return result.err
+			}
+			pending[result.index] = result.bytes
+			for {
+				frame, available := pending[next]
+				if !available {
+					break
+				}
+				written, err := writer.Write(frame)
+				if err != nil {
+					return fmt.Errorf("write frame %d to encoder: %w", next, err)
+				}
+				if written != len(frame) {
+					return fmt.Errorf("write frame %d to encoder: %w", next, io.ErrShortWrite)
+				}
+				delete(pending, next)
+				<-credits
+				next++
+				if progress != nil {
+					progress(next)
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func scheduleFrames(ctx context.Context, count int, credits chan<- struct{}, jobs chan<- int, workers *sync.WaitGroup) {
+	defer workers.Done()
+	defer close(jobs)
+	for index := range count {
+		select {
+		case <-ctx.Done():
+			return
+		case credits <- struct{}{}:
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case jobs <- index:
+		}
+	}
+}
+
+func captureFrames(ctx context.Context, capture captureFunc, jobs <-chan int, results chan<- capturedFrame, workers *sync.WaitGroup) {
+	defer workers.Done()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case index, available := <-jobs:
+			if !available {
+				return
+			}
+			buffer, err := capture(ctx, index)
+			select {
+			case <-ctx.Done():
+				return
+			case results <- capturedFrame{index: index, bytes: buffer, err: err}:
+			}
+			if err != nil {
+				return
+			}
+		}
+	}
+}

package/renderer/pipeline_test.go

@@ -0,0 +1,108 @@
+package sceneengine
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestStreamFramesOrdersConcurrentResults(t *testing.T) {
+	capture := func(ctx context.Context, index int) ([]byte, error) {
+		if index%3 == 0 {
+			time.Sleep(5 * time.Millisecond)
+		}
+		return []byte(fmt.Sprintf("%02d|", index)), nil
+	}
+	var output bytes.Buffer
+	var progress []int
+	err := streamFrames(context.Background(), 30, []captureFunc{capture, capture, capture}, &output, func(written int) { progress = append(progress, written) })
+	if err != nil {
+		t.Fatal(err)
+	}
+	var expected bytes.Buffer
+	for index := 0; index < 30; index++ {
+		fmt.Fprintf(&expected, "%02d|", index)
+	}
+	if output.String() != expected.String() {
+		t.Fatalf("frames are out of order: %s", output.String())
+	}
+	if len(progress) != 30 || progress[29] != 30 {
+		t.Fatalf("invalid progress: %v", progress)
+	}
+}
+
+func TestStreamFramesBoundsReorderingWindow(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	release := make(chan struct{})
+	var started atomic.Int64
+	capture := func(ctx context.Context, index int) ([]byte, error) {
+		started.Add(1)
+		if index == 0 {
+			select {
+			case <-release:
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			}
+		}
+		return []byte{byte(index)}, nil
+	}
+	done := make(chan error, 1)
+	go func() { done <- streamFrames(ctx, 100, []captureFunc{capture, capture}, io.Discard, nil) }()
+	deadline := time.Now().Add(time.Second)
+	for started.Load() < 4 && time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	time.Sleep(15 * time.Millisecond)
+	if value := started.Load(); value != 4 {
+		t.Errorf("expected window of four frames, got %d", value)
+	}
+	close(release)
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestStreamFramesCancelsOtherWorkersOnFailure(t *testing.T) {
+	expected := errors.New("broken frame")
+	blocked := make(chan struct{})
+	capture := func(ctx context.Context, index int) ([]byte, error) {
+		if index == 0 {
+			<-blocked
+			return nil, expected
+		}
+		close(blocked)
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if err := streamFrames(ctx, 10, []captureFunc{capture, capture}, io.Discard, nil); !errors.Is(err, expected) {
+		t.Fatalf("expected capture failure, got %v", err)
+	}
+}
+
+func TestStreamFramesHonorsCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	capture := func(ctx context.Context, _ int) ([]byte, error) { cancel(); <-ctx.Done(); return nil, ctx.Err() }
+	if err := streamFrames(ctx, 10, []captureFunc{capture}, io.Discard, nil); !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected cancellation, got %v", err)
+	}
+}
+
+type shortWriter struct{}
+
+func (shortWriter) Write(buffer []byte) (int, error) { return len(buffer) - 1, nil }
+
+func TestStreamFramesRejectsTruncatedWrites(t *testing.T) {
+	capture := func(context.Context, int) ([]byte, error) { return []byte("frame"), nil }
+	err := streamFrames(context.Background(), 2, []captureFunc{capture}, shortWriter{}, nil)
+	if !errors.Is(err, io.ErrShortWrite) {
+		t.Fatalf("expected a truncated-write error, got %v", err)
+	}
+}