From 0cf03016b20ad4ee086bc77164a00b4d54378899 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 9 Apr 2026 19:05:28 +0200
Subject: [PATCH] fix(engine): resolve external asset paths from compiled dir
 (#231)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
- Parent-relative paths (e.g. `src="../file.wav"`) silently drop media from rendered MP4
- The compiler rewrites external paths to `hf-ext/` and copies files to the compiled directory, but both the audio mixer and video frame extractor only resolved against `projectDir` — never finding them
- Now checks `compiledDir` first (matching the file server's resolution order), then falls back to `projectDir`
- Fixes both `<audio>` and `<video>` elements with external paths

## Real-world context
Reported in Slack by Abhai — a TTS comparison video using `<audio src="../tts-voxcpm2.wav">` (audio file in parent directory, composition in subdirectory) rendered successfully but the output MP4 had no audio stream. The render completed without any error, silently dropping the audio.

## Testing

### Environment
- Linux (Ubuntu 20.04), ffmpeg 4.2
- Test composition: `subdir/index.html` with `<audio id="bg-audio" src="../test-audio.wav">`, WAV file at parent directory

### Before fix (main)
```
[AUDIO-DEBUG] element.src=hf-ext/tmp/hf-test-231/test-audio.wav
              baseDir=/tmp/hf-test-231/subdir
[AUDIO-DEBUG] resolved srcPath=/tmp/hf-test-231/subdir/hf-ext/tmp/hf-test-231/test-audio.wav
              exists=false
```

- Audio mixer tries `join(projectDir, "hf-ext/...")` → file doesn't exist at that path
- Output: **9.8 KB, video stream only** (confirmed via ffprobe)
- No error logged — audio silently dropped

### After fix (this branch)
```
[AUDIO-DEBUG] element.src=hf-ext/tmp/hf-test-231/test-audio.wav
              baseDir=/tmp/hf-test-231/subdir
              compiledDir=/tmp/.../compiled
[AUDIO-DEBUG] fromCompiled=/tmp/.../compiled/hf-ext/tmp/hf-test-231/test-audio.wav
              exists=true
[AUDIO-DEBUG] resolved srcPath=/tmp/.../compiled/hf-ext/tmp/hf-test-231/test-audio.wav
              exists=true
[AUDIO-RESULT] success=true, hasAudio=true
```

- Audio mixer checks `join(compiledDir, "hf-ext/...")` first → file found
- Output: **44.6 KB, video + audio streams** (confirmed via ffprobe)

### ffprobe comparison

| Branch | File size | Streams |
|--------|-----------|---------|
| `main` | 9.8 KB | `video (h264)` only |
| `fix` | 44.6 KB | `video (h264)` + `audio (aac)` |

### Path resolution flow
1. Compiler sees `<audio src="../test-audio.wav">`
2. Compiler resolves to absolute path, maps it to `hf-ext/tmp/.../test-audio.wav`
3. Compiler copies file to `compiled/hf-ext/tmp/.../test-audio.wav`
4. Audio mixer gets `element.src = "hf-ext/tmp/.../test-audio.wav"`
5. **main**: tries `join(projectDir, src)` → not found → silent drop
6. **fix**: tries `join(compiledDir, src)` first → found → audio mixed in

### Repro
```bash
mkdir -p /tmp/test/subdir
ffmpeg -f lavfi -i "sine=frequency=440:duration=2" /tmp/test/test-audio.wav -y
# Create subdir/index.html with <audio src="../test-audio.wav" ...>
cd /tmp/test/subdir && npx hyperframes render
ffprobe -v error -show_streams output.mp4  # video only on main, video+audio on fix
```
---
 packages/engine/src/services/audioMixer.ts           | 7 +++++--
 packages/engine/src/services/videoFrameExtractor.ts  | 5 ++++-
 packages/producer/src/services/renderOrchestrator.ts | 5 +++++
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/packages/engine/src/services/audioMixer.ts b/packages/engine/src/services/audioMixer.ts
index 60221e6a9..2a928776f 100644
--- a/packages/engine/src/services/audioMixer.ts
+++ b/packages/engine/src/services/audioMixer.ts
@@ -308,6 +308,7 @@ export async function processCompositionAudio(
   totalDuration: number,
   signal?: AbortSignal,
   config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>,
+  compiledDir?: string,
 ): Promise<MixResult> {
   const startMs = Date.now();
   const tracks: AudioTrack[] = [];
@@ -324,7 +325,9 @@ export async function processCompositionAudio(
       try {
         let srcPath = element.src;
         if (!srcPath.startsWith("/") && !isHttpUrl(srcPath)) {
-          srcPath = join(baseDir, srcPath);
+          const fromCompiled = compiledDir ? join(compiledDir, srcPath) : null;
+          srcPath =
+            fromCompiled && existsSync(fromCompiled) ? fromCompiled : join(baseDir, srcPath);
         }
 
         if (isHttpUrl(srcPath)) {
@@ -339,7 +342,7 @@ export async function processCompositionAudio(
         }
 
         if (!existsSync(srcPath)) {
-          errors.push(`Source not found: ${element.id}`);
+          errors.push(`Source not found: ${element.id} (${element.src})`);
           return;
         }
 
diff --git a/packages/engine/src/services/videoFrameExtractor.ts b/packages/engine/src/services/videoFrameExtractor.ts
index e66ec2f73..d9ffc2649 100644
--- a/packages/engine/src/services/videoFrameExtractor.ts
+++ b/packages/engine/src/services/videoFrameExtractor.ts
@@ -201,6 +201,7 @@ export async function extractAllVideoFrames(
   options: ExtractionOptions,
   signal?: AbortSignal,
   config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout">>,
+  compiledDir?: string,
 ): Promise<ExtractionResult> {
   const startTime = Date.now();
   const extracted: ExtractedFrames[] = [];
@@ -216,7 +217,9 @@ export async function extractAllVideoFrames(
       try {
         let videoPath = video.src;
         if (!videoPath.startsWith("/") && !isHttpUrl(videoPath)) {
-          videoPath = join(baseDir, videoPath);
+          const fromCompiled = compiledDir ? join(compiledDir, videoPath) : null;
+          videoPath =
+            fromCompiled && existsSync(fromCompiled) ? fromCompiled : join(baseDir, videoPath);
         }
 
         if (isHttpUrl(videoPath)) {
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 8bc14558a..69a86a72f 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -692,6 +692,7 @@ export async function executeRenderJob(
     updateJobStatus(job, "preprocessing", "Extracting video frames", 10, onProgress);
 
     let frameLookup: FrameLookupTable | null = null;
+    const compiledDir = join(workDir, "compiled");
 
     if (composition.videos.length > 0) {
       const extractionResult = await extractAllVideoFrames(
@@ -699,6 +700,8 @@ export async function executeRenderJob(
         projectDir,
         { fps: job.config.fps, outputDir: join(workDir, "video-frames") },
         abortSignal,
+        undefined,
+        compiledDir,
       );
       assertNotAborted();
 
@@ -747,6 +750,8 @@ export async function executeRenderJob(
         audioOutputPath,
         job.duration,
         abortSignal,
+        undefined,
+        compiledDir,
       );
       assertNotAborted();