From d1c57b46fb42c6e836b2ec3381c0e83c3580f41f Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 17:01:36 +0000
Subject: [PATCH 01/26] Convert timed lines and cuts in a description to H3
 timed prompt notation

---
 freevideo_engine/prompt_vlm/rules.py  |  23 +++++-
 freevideo_engine/prompt_vlm/worker.py |  19 +++--
 freevideo_engine/timed_prompt.py      | 115 ++++++++++++++++++++++++++
 scripts/test_freevideo_entry.mjs      |   1 +
 web/editor.js                         |  15 +++-
 web/editor_genbar.js                  |   2 +-
 web/freevideo.js                      |   8 +-
 web/health.js                         |   2 +-
 web/studio.js                         |  10 ++-
 web/timed_prompt.js                   | 115 ++++++++++++++++++++++++++
 web/tutorial/timed-lines-1.webp       | Bin 0 -> 7678 bytes
 web/tutorial/timed-lines-2.webp       | Bin 0 -> 8714 bytes
 web/tutorial_book_content.js          |  23 ++++++
 13 files changed, 316 insertions(+), 17 deletions(-)
 create mode 100644 freevideo_engine/timed_prompt.py
 create mode 100644 web/timed_prompt.js
 create mode 100644 web/tutorial/timed-lines-1.webp
 create mode 100644 web/tutorial/timed-lines-2.webp

diff --git a/freevideo_engine/prompt_vlm/rules.py b/freevideo_engine/prompt_vlm/rules.py
index bb1e8eaf..569d4e5b 100644
--- a/freevideo_engine/prompt_vlm/rules.py
+++ b/freevideo_engine/prompt_vlm/rules.py
@@ -93,6 +93,9 @@ def instruction(value):
 The young woman (S1) says softly: <d>[Chinese] 再见了。</d> The man (S2) replies: <d>[English] Wait.</d>
 Dialogue belongs only in the first section, not in the sound sections.
 """
+    if TIMED_MARK.search(value['text']):
+        rule += ('The scene has fixed times. Keep every "At MM:SS.mmm" sentence and every [Shot n] At MM:SS.mmm cut '
+                 'exactly as given, in the same order and at the same time; add the picture, camera and sound around them.\n')
     if value['mode'] == 'ref2va':
         rule += """subject_definitions: Name each visible subject literally <Subject 1>, <Subject 2>, etc.,
 with its appearance and source <Picture N> or <Video N>. Preserve the supplied numbering.
@@ -343,10 +346,28 @@ def match_line(words):
     return text
 
 
+TIMED_MARK = re.compile(r'\bAt (\d{2}:\d{2}\.\d{3})')
+TAGGED = re.compile(r'<d>(?:\[[A-Za-z]+\])?\s*([^<\n]{1,400}?)\s*</d>')
+
+
 def missing_lines(text, scene):
     """The user's spoken lines that the rewrite does not contain at all."""
     have = plain(text)
-    return [line for line in dict.fromkeys(spoken_lines(scene)) if plain(line) not in have]
+    lines = spoken_lines(scene)
+    if TIMED_MARK.search(scene):
+        # A timed scene already wraps its dialogue as <d>[Language] ...</d>; those lines are as fixed as quoted ones.
+        lines += [line for line in TAGGED.findall(scene) if plain(line)]
+    return [line for line in dict.fromkeys(lines) if plain(line) not in have]
+
+
+def lost_marks(text, scene):
+    """The scene's fixed times (At MM:SS.mmm) that the rewrite dropped or moved out of order."""
+    have = iter(TIMED_MARK.findall(text))
+    return [mark for mark in TIMED_MARK.findall(scene) if mark not in have]
+
+
+TIMING_RETRY = ('Your rewrite lost or reordered these fixed times. Keep every sentence that starts with "At MM:SS.mmm" '
+                'and every [Shot n] At MM:SS.mmm cut exactly as given, in the same order: ')
 
 
 DIALOGUE_RETRY = ('Your rewrite left out these spoken lines. Rewrite the whole prompt again in the same format and '
diff --git a/freevideo_engine/prompt_vlm/worker.py b/freevideo_engine/prompt_vlm/worker.py
index 508621fd..078078e8 100644
--- a/freevideo_engine/prompt_vlm/worker.py
+++ b/freevideo_engine/prompt_vlm/worker.py
@@ -387,7 +387,7 @@ def rewrite(folder, value, stats):
                  persistent_model=False)
     torch, checkpoint = begin(stats)
     from transformers import AutoProcessor
-    from .rules import DIALOGUE_RETRY, TIMESTAMP_RETRY, InvalidOutput, fit_time_points, instruction, label, language, missing_lines, user_text
+    from .rules import DIALOGUE_RETRY, TIMESTAMP_RETRY, TIMING_RETRY, InvalidOutput, fit_time_points, instruction, label, language, lost_marks, missing_lines, user_text
     checkpoint('preprocess')
     preparing = time.monotonic()
     processor = AutoProcessor.from_pretrained(folder, local_files_only=True, trust_remote_code=False)
@@ -421,7 +421,7 @@ def on_token(timing):
     if len(ids) >= 1800:
         raise ValueError('context_length')
     text = processor.decode(ids, skip_special_tokens=True)
-    missing = missing_lines(text, value['text'])
+    missing, marks = missing_lines(text, value['text']), lost_marks(text, value['text'])
     rewritten, rejected = None, None
     references, late, last = [], False, text
     try:
@@ -434,8 +434,8 @@ def on_token(timing):
         if late:
             # Time points are checked first; ask for any media reference the draft also left out.
             references = error.details['missing_references']
-    if missing or references or late:
-        # Both corrections share one turn and the existing context/cache allowance.
+    if missing or marks or references or late:
+        # Every correction shares one turn and the existing context/cache allowance.
         correction = ''
         if references:
             labels = ', '.join(references)
@@ -445,7 +445,9 @@ def on_token(timing):
         if late:
             correction += TIMESTAMP_RETRY % ((value['seconds'],) * 3)
         if missing:
-            correction += DIALOGUE_RETRY + '\n'.join('- [%s] %s' % (language(line), line) for line in missing)
+            correction += DIALOGUE_RETRY + '\n'.join('- [%s] %s' % (language(line), line) for line in missing) + '\n'
+        if marks:
+            correction += TIMING_RETRY + ', '.join(marks) + '\n'
         retry = messages + [{'role': 'assistant', 'content': text}, {'role': 'user', 'content': correction}]
         retry_inputs = tokenize(processor, retry)
         if retry_allowed(retry_inputs.input_ids.shape[-1], stats):
@@ -454,7 +456,7 @@ def on_token(timing):
             # A cut-off correction is never used, not even to scale: fall back to the first draft.
             last = second if len(again) < 1800 else text
             stats.update(retry_output_tokens=len(again), rewrite_seconds=time.monotonic() - loaded)
-            if missing:
+            if missing or marks:
                 stats['dialogue_retry'] = True
             if late:
                 stats['timestamp_retry'] = True
@@ -469,7 +471,7 @@ def on_token(timing):
                     error.details['retried'] = True
                     stats['output_rejections'].append(error.details)
                     raise error
-                if len(again) < 1800 and (references or late or len(missing_lines(second, value['text'])) < len(missing)):
+                if len(again) < 1800 and (references or late or len(missing_lines(second, value['text'])) + len(lost_marks(second, value['text'])) < len(missing) + len(marks)):
                     rewritten = candidate
             except InvalidOutput:
                 if references and not late:
@@ -495,6 +497,9 @@ def on_token(timing):
     if rewritten is None:
         rejected.details = dict(rejected.details, retried=bool(stats.get('media_retry') or stats.get('dialogue_retry') or stats.get('timestamp_retry')))
         raise rejected
+    if lost_marks(rewritten, value['text']):
+        # Fixed times that survive neither pass: the caller falls back to the converted original.
+        raise InvalidOutput('timing_lost', rewritten, value)
     stats['stage'] = 'complete'
     emit(phase='complete', text=rewritten, diagnostics=dict(stats))
 
diff --git a/freevideo_engine/timed_prompt.py b/freevideo_engine/timed_prompt.py
new file mode 100644
index 00000000..5e9721fb
--- /dev/null
+++ b/freevideo_engine/timed_prompt.py
@@ -0,0 +1,115 @@
+"""Subtitle-style timed lines in a description, turned into MiniMax H3's timed prompt notation.
+
+`0:02 Lin: You are late.` becomes `At 00:02.000, Lin (S1) begins saying: <d>[English] You are late.</d>`,
+`0:07 cut: A corridor.` starts `[Shot 2] At 00:07.000, A corridor.` A description without timed lines, or one
+already written in the H3 notation, is returned unchanged. web/timed_prompt.js is the same function; both
+are checked against tests/fixtures/timed_prompt_cases.json.
+"""
+import re
+
+# The same space set as ECMAScript's \s and trim(), written out so Python and JavaScript read a line alike.
+SP = '\t\n\v\f\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff'
+SPACES = '\t\n\v\f\r \xa0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff'
+TIME = re.compile(r'^[ \t　]*([0-9]{1,3}):([0-5][0-9])(?:\.([0-9]{1,3}))?(?![0-9.:])[ \t　]*(.*)$')
+LOOSE = re.compile(r'^[ \t　]*[0-9]{1,3}:[0-9]{1,2}(?![0-9:])')
+CUT = re.compile(r'^(?:cut|CUT|Cut|切)[ \t　]*[:：][ \t　]*(.*)$')
+CUT_BARE = re.compile(r'^(?:cut|CUT|Cut|切)$')
+SPEECH = re.compile(r'^@?([^:：' + SP + r'][^:：]{0,11}?)[ \t　]*[:：][ \t　]*([^' + SP + r'].*)$')
+NAME_BREAK = re.compile(r'[,.;!?，。；！？]')
+WRITTEN = re.compile(r'\[Shot [0-9]+\]|\bAt [0-9]{2,}:[0-9]{2}\.[0-9]{3}', re.ASCII)
+CJK = re.compile('[぀-ヿ㐀-鿿]')
+ENDS = '.!?。！？…"”'
+
+
+def language(words):
+    if re.search('[぀-ヿ]', words):
+        return 'Japanese'
+    if re.search('[가-힯]', words):
+        return 'Korean'
+    if re.search('[一-鿿]', words):
+        return 'Chinese'
+    if re.search('[Ѐ-ӿ]', words):
+        return 'Russian'
+    return 'English'
+
+
+def clock(ms):
+    return '%02d:%02d.%03d' % (ms // 60000, ms // 1000 % 60, ms % 1000)
+
+
+def sentence(words):
+    words = words.strip(SPACES)
+    if not words or words[-1] in ENDS:
+        return words
+    return words + ('。' if CJK.search(words) else '.')
+
+
+def parse(text):
+    """(head lines, timed lines, errors); a timed line is {n, ms, kind, who, words}."""
+    head, lines, errors = [], [], []
+    for n, raw in enumerate(re.split(r'\r\n|\r|\n', text), 1):
+        found = TIME.match(raw)
+        if not found:
+            if LOOSE.match(raw):
+                errors.append({'line': n, 'code': 'bad_time'})
+            elif raw.strip(SPACES):
+                head.append(raw.strip(SPACES))
+            continue
+        minutes, seconds, fraction, rest = found.groups()
+        ms = (int(minutes) * 60 + int(seconds)) * 1000 + int((fraction or '').ljust(3, '0'))
+        rest = rest.strip(SPACES)
+        row = {'n': n, 'ms': ms, 'kind': 'event', 'who': '', 'words': rest}
+        cut, speech = CUT.match(rest), SPEECH.match(rest)
+        if cut or CUT_BARE.match(rest):
+            row.update(kind='cut', words=(cut.group(1) if cut else '').strip(SPACES))
+        elif speech and not NAME_BREAK.search(speech.group(1)):
+            row.update(kind='speech', who=speech.group(1).strip(SPACES), words=speech.group(2).strip(SPACES))
+        if not row['words']:
+            errors.append({'line': n, 'code': 'empty_cut' if row['kind'] == 'cut' else 'bad_time'})
+            continue
+        lines.append(row)
+    return head, lines, errors
+
+
+def convert(text, seconds, speakers=None, offset=0):
+    """{text, errors, timed}: errors name the lines left out ({line, code}); the caller stops on any.
+    Times are read on a ruler that starts `offset` seconds before this text's first second."""
+    if not isinstance(text, str) or WRITTEN.search(text):
+        return {'text': text, 'errors': [], 'timed': False}
+    head, lines, errors = parse(text)
+    if not lines and not errors:
+        return {'text': text, 'errors': [], 'timed': False}
+    limit = round(seconds * 1000)
+    kept = []
+    shift = round(offset * 1000)
+    for row in lines:
+        row['ms'] -= shift
+        if row['ms'] < 0 or row['ms'] >= limit:
+            errors.append({'line': row['n'], 'code': 'out_of_range'})
+        else:
+            kept.append(row)
+    errors.sort(key=lambda e: e['line'])
+    ids = dict(speakers or {})
+    shots = [{'ms': 0, 'open': ' '.join(head), 'parts': []}]
+    for row in sorted(kept, key=lambda r: (r['ms'], r['kind'] != 'cut', r['kind'] == 'speech')):
+        if row['kind'] == 'cut' and row['ms'] > 0:
+            if shots[-1]['ms'] == row['ms']:
+                shots[-1]['open'] = (shots[-1]['open'] + ' ' + sentence(row['words'])).strip(SPACES)
+            else:
+                shots.append({'ms': row['ms'], 'open': sentence(row['words']), 'parts': []})
+            continue
+        at = 'At %s, ' % clock(row['ms']) if row['ms'] > 0 else ''
+        if row['kind'] == 'cut':
+            shots[0]['open'] = (shots[0]['open'] + ' ' + sentence(row['words'])).strip(SPACES)
+        elif row['kind'] == 'event':
+            shots[-1]['parts'].append(at + sentence(row['words']))
+        else:
+            if row['who'] not in ids:
+                ids[row['who']] = max(ids.values(), default=0) + 1
+            shots[-1]['parts'].append('%s%s (S%d) begins saying: <d>[%s] %s</d>'
+                                      % (at, row['who'], ids[row['who']], language(row['words']), row['words']))
+    out = []
+    for index, shot in enumerate(shots, 1):
+        label = '[Shot 1]' if index == 1 else '[Shot %d] At %s,' % (index, clock(shot['ms']))
+        out.append(' '.join(part for part in (label, shot['open'], *shot['parts']) if part))
+    return {'text': ' '.join(out), 'errors': errors, 'timed': True}
diff --git a/scripts/test_freevideo_entry.mjs b/scripts/test_freevideo_entry.mjs
index 891d3781..6c6e6f7b 100644
--- a/scripts/test_freevideo_entry.mjs
+++ b/scripts/test_freevideo_entry.mjs
@@ -129,6 +129,7 @@ test('main browser entry registers both views and preserves node hooks', async t
             .replace("import { startUpdateChecks } from './updates.js';", 'const {startUpdateChecks} = globalThis.__freevideoEntryTest;')
             .replace("import { startDoneNotify, askDesktopPermission, DESKTOP_SETTING } from './done_notify.js';", 'const {startDoneNotify} = globalThis.__freevideoEntryTest; const askDesktopPermission = (...args) => globalThis.__permissionAsks.push(args); const DESKTOP_SETTING = "FreeVideo.DoneNotify.Desktop";')
             .replace("import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows, mediaNodeOf } from './prompt_references.js';", 'const {attachReferencePicker,referenceItems,syncReferencePrompt,referenceInputs,mediaRows} = globalThis.__freevideoEntryTest; const mediaNodeOf = () => null;')
+            .replace("import { timedText } from './timed_prompt.js';", 'const timedText = text => text;')
             .replace("import { expandCast } from './cast_mention.js';", 'const {expandCast} = globalThis.__freevideoEntryTest;')
             .replace("import { outputDownloadURL } from './output_download.js';", 'const {outputDownloadURL} = globalThis.__freevideoEntryTest;')
             .replace("import { shareButton } from './share.js';", 'const {shareButton} = globalThis.__freevideoEntryTest;')
diff --git a/web/editor.js b/web/editor.js
index 995545fc..815c31cf 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -38,6 +38,7 @@ import {optionalText, clonePrompt, allowEmptyPrompt} from './optional_inputs.js'
 import {outputNotWritable} from './error_panel.js';
 import {repairAction} from './repair_hint.js';
 import {expandCast} from './cast_mention.js';
+import {problem as timedProblem, timedText} from './timed_prompt.js';
 const editorStyles = Promise.all(['result_actions.css', 'editor.css', 'editor_expand.css', 'editor_tracks.css', 'editor_frame.css', 'editor_adjust.css', 'editor_adjust_picture.css', 'editor_preview_picture.css', 'editor_select.css', 'editor_menu.css', 'editor_text.css', 'editor_notes.css', 'editor_transport.css'].map(name => {
     const style = document.createElement('link'); style.rel = 'stylesheet'; style.href = new URL(name, import.meta.url).href;
     const ready = 'sheet' in style ? new Promise(resolve => { style.onload = style.onerror = resolve; }) : Promise.resolve();
@@ -333,6 +334,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
             const text = textLongText(t, Number.isInteger(value.limit) ? value.limit : 8000);
             out(text); return {ok: false, reason: code, say: text};
         }
+        if (code === 'timed_text') { out(value.say); return {ok: false, reason: code, say: value.say}; }
         if (PARTS_LIMIT_CODES.includes(code)) {
             const [en, zh] = (value.said || []).map(text => typeof text === 'string' && text ? text.slice(0, 200) : null);
             const text = en && zh ? t(en, zh) : partsLimitText(code, t, Number.isInteger(value.limit) ? value.limit : null);
@@ -517,7 +519,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 // Each part goes with its own description, as written while it waited.
                 const texts = Object.fromEntries(clips.map(clip => [clip.id, clip.text.trim() || entry.text]));
                 try { await actions.generate({text: texts[clips[0].id], texts, selection, allowEmpty: entry.allowEmpty === true}); }
-                catch (value) { const reason = error(value, 'generate'); if (reason && !PARTS_LIMIT_CODES.includes(reason.reason)) genbar?.say(reason.say); }
+                catch (value) { const reason = error(value, 'generate'); if (reason && !PARTS_LIMIT_CODES.includes(reason.reason) && reason.reason !== 'timed_text') genbar?.say(reason.say); }
             }
         } finally { startingHeld = false; }
     }
@@ -993,6 +995,12 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                     const full = problem.code === 'chain_too_long' && beforeKeys.some(key => store.knownLineage()[key]?.parts >= model.RULES.maxParts);
                     throw Object.assign(new Error(full ? 'chain_source_full' : problem.code), {code: full ? 'chain_source_full' : problem.code, limit: problem.limit});
                 }
+                // Times in a description are read on the ruler; a part that continues keeps its text as typed.
+                const timedSpan = block => ({offset: (model.find(prepared, block.id)?.start ?? 0) / model.FPS, seconds: block.frames / model.FPS});
+                for (const block of request.blocks.filter(block => !block.after)) {
+                    const {offset, seconds} = timedSpan(block), say = timedProblem(block.text, seconds, t, offset);
+                    if (say) throw Object.assign(new Error('timed_text'), {code: 'timed_text', say});
+                }
                 const sizes = new Map(store.sources);
                 for (const key of beforeKeys.filter(key => key?.startsWith('chain:'))) {
                     const job = await store.chain(key.split(':')[1]);
@@ -1016,7 +1024,8 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 // continues carries only the pictures the engine keeps for it, and is numbered among them.
                 const castRows = panel.references?.available() ? panel.references.rows?.() ?? [] : [];
                 const blocks = request.blocks.map(({before, ...block}, i) => ({...block, seed: seed + i,
-                    text: expandCast(block.text, castRows, {continued: Boolean(block.after)}).text}));
+                    text: expandCast(block.after ? block.text : (({seconds, offset}) => timedText(block.text, seconds, offset))(timedSpan(block)),
+                        castRows, {continued: Boolean(block.after)}).text}));
                 const job = await store.startChain({...frozen, blocks, queue: true});
                 if (!job && !store.generationAvailable) {
                     if (epoch === projectEpoch) {
@@ -1038,7 +1047,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 if (epoch === projectEpoch) {
                     if (ids.length) state.settle(record => model.settle(record, ids, 'draft'));
                     // A length limit is the user's to change and is said once in the notice; there is nothing to report.
-                    if (!PARTS_LIMIT_CODES.includes(value?.code)) {
+                    if (!PARTS_LIMIT_CODES.includes(value?.code) && value?.code !== 'timed_text') {
                         failures.submission(value, frozen, text); submissionFailure = JSON.stringify(state.selection);
                     }
                     genbar?.update(null);
diff --git a/web/editor_genbar.js b/web/editor_genbar.js
index 7a77500e..7d2d3e4c 100644
--- a/web/editor_genbar.js
+++ b/web/editor_genbar.js
@@ -302,7 +302,7 @@ export function createEditorGenbar(host, {state, t, actions, text = ''}) {
         }
         // A specific reason is said once; the planning limits are already shown above.
         catch (error) { const result = actions.error(error, 'generate'); reason = result?.say || '';
-            if (result?.say && !['chain_too_long', 'chain_part_too_short', 'chain_short_parts'].includes(result.reason)) say(result.say, false, ['Editor generation', '剪辑器生成']);
+            if (result?.say && !['chain_too_long', 'chain_part_too_short', 'chain_short_parts', 'timed_text'].includes(result.reason)) say(result.say, false, ['Editor generation', '剪辑器生成']);
             else if (!result && !note.textContent) { reason = t('Could not start. Try again.', '没能开始，请重试。'); say(reason, false, ['Editor generation', '剪辑器生成']); } }
         finally { pressing.delete(key); render(); }
         return reason;
diff --git a/web/freevideo.js b/web/freevideo.js
index dd2e1db0..5491d098 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -19,6 +19,7 @@ import { agentInterfaceState } from './agent_connect.js';
 import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows, mediaNodeOf } from './prompt_references.js';
 import { expandCast } from './cast_mention.js';
 import { requestText } from './prompt_sections.js';
+import { timedText } from './timed_prompt.js';
 import { outputDownloadURL } from './output_download.js';
 import { shareButton } from './share.js';
 import { reportFileName } from './report_issue.js';
@@ -829,8 +830,11 @@ app.registerExtension({
                     const owner = this;
                     // Replace person asks for its prefix here, where every way of running the node reads the text.
                     prompt.serializeValue = () => {
-                        const body = expandCast(requestText(prompt.value, owner.properties?.freevideo_prompt_versions),
-                            mediaRows(owner), {continued: Boolean(owner.freevideoContinues?.())}).text;
+                        const continued = Boolean(owner.freevideoContinues?.());
+                        // Subtitle-style time lines become H3's timed prompt; a long video made in parts keeps the typed text.
+                        const typed = requestText(prompt.value, owner.properties?.freevideo_prompt_versions);
+                        const timed = !continued && owner.freevideoSingleRun?.() ? timedText(typed, Number(owner.widgets?.find(w => w.name === 'seconds')?.value)) : typed;
+                        const body = expandCast(timed, mediaRows(owner), {continued}).text;
                         return swapState(mediaNodeOf(owner)) ? withPrefix(body) : body;
                     };
                 }
diff --git a/web/health.js b/web/health.js
index d04f2c34..80becefd 100644
--- a/web/health.js
+++ b/web/health.js
@@ -13,7 +13,7 @@ const t = (en, zh) => cn ? zh : en;
 // launcher.js removes this flag during setup; read it before that.
 const launchVisit = query.get('freevideo') === 'launch';
 // Every script this folder ships; a test keeps the list in step with web/*.js.
-export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_confirm_settings.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'chain_rules.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
+export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_confirm_settings.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'chain_rules.js', 'timed_prompt.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'image_lora.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
diff --git a/web/studio.js b/web/studio.js
index fbf9283a..59e20751 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -24,6 +24,7 @@ import { createStudioQueue, randomSeed, turnNodeOn } from './studio_queue.js';
 import { isNetworkTypeError, connectionLostText, wrappedFetchOnly } from './browser_extension.js';
 import { attachReferencePicker, referenceItems, enhancementMedia, syncReferencePrompt, referenceInputs, mentionAt, handleNames, mediaRows } from './prompt_references.js';
 import { attachTermSuggest } from './prompt_terms.js';
+import { problem as timedProblem, timedText } from './timed_prompt.js';
 import { castInRows, expandCast, mentionHandle, mentionState, mentionedIds, restoreCast, withCharacter, MAX_PICTURES_EACH } from './cast_mention.js';
 import { attachMentionOverlay } from './cast_overlay.js';
 import { openCastLibrary } from './cast_source.js';
@@ -820,7 +821,10 @@ export function openStudio(node, {extendFrom = null} = {}) {
     const castChanged = event => { if (String(event.detail) === String(mediaNode?.id)) { castOverlay.refresh(); references.refresh(); announceCast(); } };
     window.addEventListener('freevideo-media', castChanged);
     node.freevideoContinues = () => Boolean(extension.source);
-    cleanup.push(() => { castLibrary?.destroy?.(); castLibrary = null; sceneLibrary?.destroy?.(); sceneLibrary = null; window.removeEventListener('freevideo-media', castChanged); prompt.removeEventListener('input', announceCast); castOverlay.dispose(); delete node.freevideoContinues; });
+    // Time lines are read for one video made in a single run; parts of a long video keep the typed text.
+    const timedRun = () => !extension.source && (lengthControl?.plan ? lengthControl.plan.count === 1 : Number(value(node, 'seconds')) <= 15);
+    node.freevideoSingleRun = timedRun;
+    cleanup.push(() => { castLibrary?.destroy?.(); castLibrary = null; sceneLibrary?.destroy?.(); sceneLibrary = null; window.removeEventListener('freevideo-media', castChanged); prompt.removeEventListener('input', announceCast); castOverlay.dispose(); delete node.freevideoContinues; delete node.freevideoSingleRun; });
     openCastLibrary({api, text: t, viewURL: view, uploadOne: castUpload, onChange: () => { castOverlay.refresh(); references.refresh(); }})
         .then(library => { if (disposed) library?.destroy?.(); else castLibrary = library; });
     openCastLibrary({api, text: t, viewURL: view, uploadOne: castUpload, kind: 'setting', onChange: () => { references.refresh(); }})
@@ -828,7 +832,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
     let requestAssets = null, rewriteSubjects = [];
     const enhancer = createPromptEnhancer({node, input: prompt, editor: promptEditor, api, t, starter, issueButton,
         // One rewrite runs at a time, so the subjects of the text it was given are the ones its numbers refer to.
-        prepare: text => { const out = expandCast(text, mediaRows(node), {continued: Boolean(extension.source)}); rewriteSubjects = out.subjects; return out.text; },
+        prepare: text => { const out = expandCast(timedRun() ? timedText(text, Number(value(node, 'seconds'))) : text, mediaRows(node), {continued: Boolean(extension.source)}); rewriteSubjects = out.subjects; return out.text; },
         restore: text => restoreCast(text, rewriteSubjects), display: text => shownRewrite(text, t('en', 'zh')) ?? text,
         // The rewrite has its own report; the video's report entry is not touched.
         onReport: row => { node.freevideoPromptReportId = row.rewrite_report_id || row.report_id; },
@@ -1916,6 +1920,8 @@ export function openStudio(node, {extendFrom = null} = {}) {
             const missing = swapMissing(swapState(mediaNode));
             if (missing) { status.dataset.error = 'true'; status.textContent = swapMissingText(missing, t); return; }
         }
+        const timedNote = !prompt.disabled && timedRun() ? timedProblem(prompt.value, Number(value(node, 'seconds')), t) : '';
+        if (timedNote) { status.dataset.error = 'true'; status.textContent = timedNote; prompt.focus(); return; }
         const chosenMode = runMode, batchCount = chosenMode === 'batch' ? Number(count.value) : 1;
         const originalSeed = value(node, 'seed'), seedMode = mode.value;
         // A request that is not accepted leaves the node mode as the user had it; a retry turns it on again.
diff --git a/web/timed_prompt.js b/web/timed_prompt.js
new file mode 100644
index 00000000..9a08cf3e
--- /dev/null
+++ b/web/timed_prompt.js
@@ -0,0 +1,115 @@
+// Subtitle-style timed lines in a description, turned into MiniMax H3's timed prompt notation.
+// Same function as freevideo_engine/timed_prompt.py; both are checked against tests/fixtures/timed_prompt_cases.json.
+const TIME = /^[ \t　]*(\d{1,3}):([0-5]\d)(?:\.(\d{1,3}))?(?![\d.:])[ \t　]*([^\r\n]*)$/;
+const LOOSE = /^[ \t　]*\d{1,3}:\d{1,2}(?![\d:])/;
+const CUT = /^(?:cut|CUT|Cut|切)[ \t　]*[:：][ \t　]*([^\r\n]*)$/;
+const CUT_BARE = /^(?:cut|CUT|Cut|切)$/;
+const SPEECH = /^@?([^:：\s　][^:：]{0,11}?)[ \t　]*[:：][ \t　]*(\S[^\r\n]*)$/;
+const NAME_BREAK = /[,.;!?，。；！？]/;
+const WRITTEN = /\[Shot \d+\]|\bAt \d{2,}:\d{2}\.\d{3}/;
+const CJK = /[぀-ヿ㐀-鿿]/;
+const ENDS = '.!?。！？…"”';
+
+export function language(words) {
+    if (/[぀-ヿ]/.test(words)) return 'Japanese';
+    if (/[가-힯]/.test(words)) return 'Korean';
+    if (/[一-鿿]/.test(words)) return 'Chinese';
+    if (/[Ѐ-ӿ]/.test(words)) return 'Russian';
+    return 'English';
+}
+
+const pad = (value, width) => String(value).padStart(width, '0');
+export const clock = ms => `${pad(Math.floor(ms / 60000), 2)}:${pad(Math.floor(ms / 1000) % 60, 2)}.${pad(ms % 1000, 3)}`;
+
+function sentence(words) {
+    words = words.trim();
+    if (!words || ENDS.includes(words[words.length - 1])) return words;
+    return words + (CJK.test(words) ? '。' : '.');
+}
+
+export function parse(text) {
+    const head = [], lines = [], errors = [];
+    text.split(/\r\n|\r|\n/).forEach((raw, index) => {
+        const n = index + 1, found = TIME.exec(raw);
+        if (!found) {
+            if (LOOSE.test(raw)) errors.push({line: n, code: 'bad_time'});
+            else if (raw.trim()) head.push(raw.trim());
+            return;
+        }
+        const [, minutes, seconds, fraction, rest0] = found, rest = rest0.trim();
+        const ms = (Number(minutes) * 60 + Number(seconds)) * 1000 + Number((fraction || '').padEnd(3, '0') || 0);
+        const row = {n, ms, kind: 'event', who: '', words: rest};
+        const cut = CUT.exec(rest), speech = SPEECH.exec(rest);
+        if (cut || CUT_BARE.test(rest)) Object.assign(row, {kind: 'cut', words: (cut ? cut[1] : '').trim()});
+        else if (speech && !NAME_BREAK.test(speech[1])) Object.assign(row, {kind: 'speech', who: speech[1].trim(), words: speech[2].trim()});
+        if (!row.words) { errors.push({line: n, code: row.kind === 'cut' ? 'empty_cut' : 'bad_time'}); return; }
+        lines.push(row);
+    });
+    return [head, lines, errors];
+}
+
+export function convert(text, seconds, speakers = null, offset = 0) {
+    if (typeof text !== 'string' || WRITTEN.test(text)) return {text, errors: [], timed: false};
+    const [head, lines, errors] = parse(text);
+    if (!lines.length && !errors.length) return {text, errors: [], timed: false};
+    const limit = Math.round(seconds * 1000), kept = [];
+    const shift = Math.round(offset * 1000);
+    for (const row of lines) {
+        row.ms -= shift;
+        if (row.ms < 0 || row.ms >= limit) errors.push({line: row.n, code: 'out_of_range'});
+        else kept.push(row);
+    }
+    errors.sort((a, b) => a.line - b.line);
+    const ids = Object.assign(Object.create(null), speakers);
+    const shots = [{ms: 0, open: head.join(' '), parts: []}];
+    const rank = row => [row.kind !== 'cut', row.kind === 'speech'];
+    const order = kept.map((row, i) => [row, i]).sort(([a, i], [b, j]) => a.ms - b.ms
+        || rank(a)[0] - rank(b)[0] || rank(a)[1] - rank(b)[1] || i - j);
+    for (const [row] of order) {
+        const last = shots[shots.length - 1];
+        if (row.kind === 'cut' && row.ms > 0) {
+            if (last.ms === row.ms) last.open = `${last.open} ${sentence(row.words)}`.trim();
+            else shots.push({ms: row.ms, open: sentence(row.words), parts: []});
+            continue;
+        }
+        const at = row.ms > 0 ? `At ${clock(row.ms)}, ` : '';
+        if (row.kind === 'cut') shots[0].open = `${shots[0].open} ${sentence(row.words)}`.trim();
+        else if (row.kind === 'event') last.parts.push(at + sentence(row.words));
+        else {
+            if (!(row.who in ids)) ids[row.who] = Math.max(0, ...Object.values(ids)) + 1;
+            last.parts.push(`${at}${row.who} (S${ids[row.who]}) begins saying: <d>[${language(row.words)}] ${row.words}</d>`);
+        }
+    }
+    const out = shots.map((shot, index) => {
+        const label = index === 0 ? '[Shot 1]' : `[Shot ${index + 1}] At ${clock(shot.ms)},`;
+        return [label, shot.open, ...shot.parts].filter(Boolean).join(' ');
+    });
+    return {text: out.join(' '), errors, timed: true};
+}
+
+const shortClock = seconds => `${Math.floor(seconds / 60)}:${pad(Math.floor(seconds % 60), 2)}`;
+
+// The first line the user has to fix, in one sentence; '' when every timed line can be used.
+export function problem(text, seconds, t, offset = null) {
+    const {errors} = convert(text, seconds, null, offset ?? 0);
+    if (!errors.length) return '';
+    const {line, code} = errors[0], raw = text.split(/\r\n|\r|\n/)[line - 1] || '';
+    const time = (/^[ \t　]*(\d{1,3}:\d{1,3}(?:\.\d{1,3})?)/.exec(raw) || [, ''])[1];
+    const length = shortClock(seconds);
+    if (code === 'out_of_range' && offset !== null) {
+        const range = `${shortClock(offset)}\u2060–\u2060${shortClock(offset + seconds)}`;
+        return t(`Line ${line} is at ${time}, outside this part (${range}). Change it to a time within this part.`,
+            `第 ${line} 行的时间 ${time} 超出这一段（${range}），请改为这段内的时间。`);
+    }
+    if (code === 'out_of_range') return t(`Line ${line} is at ${time}, beyond the video length (${length}). Change it to a time within ${length}.`,
+        `第 ${line} 行的时间 ${time} 超出视频时长（${length}），请改为 ${length} 以内的时间。`);
+    if (code === 'empty_cut') return t(`Line ${line} has nothing after the cut. Describe the new shot.`, `第 ${line} 行的“切：”后面没有内容，请写出新镜头的画面。`);
+    return t(`The time "${time}" on line ${line} is not valid. Write it as minutes:seconds, for example 0:05.`,
+        `第 ${line} 行的时间“${time}”无法识别，请按“分:秒”书写，例如 0:05。`);
+}
+
+// What the model and the generator read: the converted text, or the typed text while a line is unusable.
+export function timedText(text, seconds, offset = 0) {
+    const done = convert(text, seconds, null, offset);
+    return done.errors.length ? text : done.text;
+}
diff --git a/web/tutorial/timed-lines-1.webp b/web/tutorial/timed-lines-1.webp
new file mode 100644
index 0000000000000000000000000000000000000000..f709f45be671c250767e0b950fd7f9d55f2fbe97
GIT binary patch
literal 7678
zcmaKxRa6~8)2;^#5Fog_ZXgic-8Fb{cL?t8E*nU&1SeQ<C%C)2y9EdYclJKy|1Q4&
z;+#{xs^;nHcXe0ST+JFaIce!zQUK7B5?9ew;njW%0070Shrs~d03atJp)v&XIt5^c
z{zZ6J0I+v(b5WBKr_k2Xr9j*QU|z@nn2DLI(|_py8edhn3;)s1GXGx{|NkVixrM9Q
ztK|IEX<S|pf2|4Um2s^8!}R~y^gk^4k3HR-++H;*|JX%CP2!c!Uzy(Of3fNRVlyX~
zfBLvrji9}q`@ggP*}vPNS~z@Ce|;joItkzkr~xv7_`mzV&R@+j9{_l7001uWzd6%y
z0MHZ;00b-l&C%on0D2ezG*13E_urm4nYftz&vx*y5!TWY04|FG08Iw~u%`gvt=|8v
zy@vlsZ4|FdB(HTjz78wE4zK_y06D+`Fatik5<9>OumRk!Z<qp!1OQarfGilsaF`xI
zSdI!Tm7h<EY2%(q4<A<7<hpPO2Rp+nVy(q}&#o>~l<4>lYWx)RNcsYoJvajQ#3PHo
zMLq@{3jA~z^kR7nb02&L^OEuGsbh4>qJln?ph&)o9*(}ma&NTZpUq{_76>7KFme!?
z3?%NX_MyIa?CX?&4uH&_sy_z$cgSDi-zO}vlt9&9svwI`b?2S8f8qSQq3@3o?*Co{
z{s~+XaS`eCae>6%FF(T#O)^5tUIyn-=E%PWdP4GEc3&dzSk@;EHm3sVIs+k!k7X}L
zYjF3)7b0iS4G{-uBNPhVz3IHkIfF3ds6$SlsPD&bVV->-Iv>c-p}%r|cS4~%&#Es8
zFOGNQ*G4y;<AKmS=Lg4|$?MHs5%0i}K<G0(MCy6<x%f``vhyKu;B~`>I|b<MYTBR4
zn!}UHml;@LW0G;Dx6t@~`ZfD)0;1{(EPqSE#6X)E6Oi7<&bK^B?RP}xX6ze5re@h;
zU!MM6P$S4q1hl*E?3-cdY?Al4nMLayH(+B)=V9iAh(#jxH<5|K8Ju5co$$c-i&;la
z)@0U#(_`{UF(r!{@)H#H0_?A-%YJ0tZCT=tfw2Da3U|yN5bqGy$)6iibZm2$J66c7
zpC0BQpM4*Kww;Ww+{VYaq`=WHMDuZH%yBP}!}^%*bT2CnRxI@L4$}71-nEqw?X#9P
zVX9|}MXN(DQmFy1s9M`5@VkYZyk|ee6UkIjccY#s#}>ozJHOoDmHoFG8DrAw->h+Q
zIx=dGB^=|uvS&Ps(kzN2oZo+>nGu-4m{8<++}4QWuFqH(3;kMV&zv6Jk3);v?#!OC
z0w|V*h@0#c-$PNGP`C+g*za1dGQ=OC7Azst!X!f&$n5KRqxQR#*3qWRzjx@Q1hkNN
zxJE7cB9D*}%|%3?7zdYg7%wl@T6OLhi@X!mNXVbdTvd*&Wz$k`Lg`$5m*wduhqPn)
z;7q?rJ!jfz)3TiT^}CGUh0~@SL9l0wj<+9{B)(~EQd4Cy3v5~_8+e}8>!ROn3?+3D
zN6sD1dg$1j<;AvGzq8JNUnkgU?wEl`x{%yJIJ4y%aMR0moQGxjDL`85x0Lv#PP_+m
zZ{(1hx4F`}Fqrpa0LB_$h(PUb@2ilrW5)T7z2Gr!9?x0xbvJ`sX&vZv27`cgPWY6#
zwmL_^q2JccN+EEIKt-sf3rebOxs9-yfJXp)`}Eq@+9^f`f1VO90DwHqXG!Yy#CED+
zR#BBh<g6%6q9hmc<4e?IRk&N_pXwgL>ew7`e>d#EZ%<6|T0M1_9>PIxhu1ks9+WB~
zq-<AQm^y%8U*TJ&%tXWnJd`32hXMh>2%VAk8LPRyH^i{)gOv_PZXT!G3G6}=ne(?q
zXVD!We}wFdyXBYZ*>V(JN$&wmv3|Jdqia0h!N**cLgOz-mqoFzS=9zH&59Jc)nFP5
z{Z(al!Use0RX?*sNy&uU8;g7i>0P~Qj<zZ@J7$20uq}OZeHCJQ00es(=v|=C{FW`G
z3pq=Bsi(NqBVqhrjWbeCM@E*%y_&Tkmj+S^u5}HU5mTaLiffe*$f)=`o-`i$@K%L2
zXS;6BO?Biwc7F7WPGn0DW6^xW;TrDTbaLd{=c_uoOX_|1I?}T`RgqHkrmsOA)@ud0
z{goXWEO2wwWhra$n~rVoQe@r2--#z!*>2Ho=lfjyPbYbS@hi7+;S~4x<4D?7;x#n0
z4$$+2A5P*SY!wKgvOhlp-0Mkh9?L5Ya3qX_c-N~IYRnR(!e%gZr<32(JsKT*a(VKf
z<it4S2MoD?Y^Q%T?dRzWb!{(TP#50F?!$7;oXHACX;(XuJyTR`O0iC;24N-DH&5mi
z?(h4Z;;Y>tr}A)SWsJZpb46ToEE~%~<no<-#UxbQQ9#@amQ6wFvDiMtM+xs)dz3~W
z2^|fs_xEkj2m3Lncn7WU$BMBX47|ux9X_xGz6TiIfSE^iMmO8nNrQq?ze;tr=n(rW
zz4-V0aG;uz%F09EcF(<Rjfs83uH(#+rz1-g9y3zdv%~q;rb|_Cr?h5+yvpOYT57Sk
z@#Z60i+iv~PGB)ouB^Tl6lBJY`5=yIM{S6~%isA{qEGoDPOgZ>RapIHS?B5eOUf{E
z+Xlx%-;Rc?ne6OPsD*eTi@5#VyXgBxsdENBWu>Kqvp3!k<rQ^08MC-Rwb$209?iAX
zD8@!tyjDuQ$G7;;GiYWp$o6elN?^Bn|F&({79@M>s5it^-KUe3CQp93G1SMo*X91|
zBo*i>Oe7=_#>?7zyfVxpto$!4Wz9+8+2<pYCW)>aBUgrU8%)>9Vs~~m^Ud0EVuRpp
z;{qz-5vyh#f^RWf43{NeQ*1r_e-!CeW$uMJcofus!^tXVS=X+AH<JW|E!#7rX7_2W
z&)$&%1Id8fu79vIY_F-t&m9)?=lloj)o@>zWa(BtN3K?vzwnYm&)oCdQ*U#0aR1ap
z(9GpN?N!EV4Ow(?EB!?2X^s`&iz1SZ2(h#_h8-swMl5i3KE4TWw^GrMnOuK4hQH*C
zt606#u6h5Vd4y8K9h@O9?36$ilfkeehcnX}Uew4j2~)P<2j-prG}C8d?CmD;Xe@xM
zV<I4vdr}NSU2d@~bkdV&hWdRv)w`cRIMB7{p7L&V^Fk`GTk&)Cnt0b=X9sFm;o+cT
z<5r?yXH(<Ex+!+V@Z+`W!M0(LPtdNdKMM~ZI@G{hPs#jx^7rq0S`f)en;(qhG4)id
zZ8%^mGyLU#o9p~6#->OADFN5jor_Cgz^>KQf7#oruf-1C6UAk2M8el*6_u9mP;z-j
z(8i4&M_5|F)r#M)Mfel{u5KCfeIzvP^h<$^PvA*|>)tfTPh%_c_vX2!*A8f#`C}GG
zNUTFA=a4!0DKh$f)@*5HBqBhnfp$!K69OC|=)jIAgiVhhmY^Fkycsu9eJes>X1vTx
zM@dNGwfT&#yNyV9&ZEZBZ&^Ruc!S-#x9O&KE4^6#{;1Q``Sa6S`xR6XgMJGMUkD7f
z7DKtAh3jDR5H%S@_L}{0#Y@BmS}fv6MGhwcQ8B!w9*aWUMvm=bjUC5j#)AVVI#yY)
z-f2)h7E}mfB8B3*aXGKB?q@GvphNwCC6*J<H!>YwvGpL9*JunGvMZKH^NPw|&PS!q
zpQ;=lpw*d#GNmjvmbFRt=X_h(vCx#FW9>dpz;(<2X}`r&IC=c%>lmCu<4!kZf7dkp
zz!>8xxldn<=%XB1gDLK|<5?*_=-6--q+Jzno-nGIlDvpr3fa;2T;r$ld7?H-8+QeN
z4~)M*UktXbitRE<1G_U*9!9%cifI%|t?S0gF0n#M?C7@FNcL08Z6oU2mxV+}q<X2v
z;QD537NH{ZFN&nsJHYrb)nw)tNY{y^|2rG#BTaX7B4)zTfaaL;RXHVjeJjg&#e`4G
zsMEQGy^OOpi1)}y%i103qj7`K94JG5;oa@CN5Wj-M`~|`gf`Dk8=SIQ&xn(V)xn+9
z+NtHZr~^rb1&kW0p@skg$<kCe#FQV#a8>o-0P%2orPB*5m)a$>UpeA`$aN8*qz$!M
zJ<mPhOAC&Y;jZ)Gk$PQOo-|@x`Erg~1d^R7X*o)~?D>#W>tqcHi_~A%8N`VJ_?E0m
zS*X`z%MmLAyFuEDT~hAmARJZVuT~zw8%LIArkS*;0Bzr^Q7!tc#HmD!=gMIEI7ZR|
zV$?wpgt#iSpv~HGOekLLf!pQ!U-e)7I2K*-c-OAl`##ciCC+2EuhVI5Ol^0w%yDv;
z`btbvL?$!&hltZPP4~_J(ZXU9$Tys;+CM^uFTSYRn;FhV;0!A<Lnt0_t^UB_j9gf?
zlKaCcPwY3N(cUFLfP_LDh~$psJcWIWp3MNyb>1oD@6y>|pp)|#OPP;6Gl>5^4^l!I
zzR1_5@Zn9&UYi9Mes6~#A6KZPj$Nij-N1M-VvczHtqhzaq#yx%{pvTWV(GP&!^C0?
ztC;?Tah9m#74;-DjW-ejOmKd03ADS=5j=k-aYjqmBJq(DT#>DFTT@6L=1~d<L}pIL
zn<DFCE{3(<&F;egQSS>PBs_)#)2i~K_tb}yq2@aY<~!?J_IUQ(-1ZdAyf4A`(xizO
zu|PUnA9*)XgvURj81<p@!<qtG*I#dA1_S@v!<2)%2Dx&puGQKtXVbZ=yW{<I)+t3j
z^EW|GY9X_I=as=j9vw;Ra|OJM^hF_Uy<S@c77DlXJ$3yNFgKs+d-;gQ#51D~$34wc
zM3cTk+6e2)x`P=T>m>FA;_EQovJKHP-$fkFFXdfFanH&AA|EkNbs##;)3{my)p{SC
zAWPwAwWup}pNN#RrCTB%nylKSOeDF`e5@u-q`cv;!h0cmvA7+MW2=uFRXD<2V@0~u
zH0ISUX4;I5uCbG?1jh}icZ5*(0TE~tSaa#$IE`8qoY7$f{v;ay#N<xpZcNLFvd@uu
zkT)-Ro5y8M$2nBWGaFLU7as6CCW-5FR}!JFdTIA{d7B^4ZSNvrefw?di{d<WLNy1z
zA)bt^8Foowun?k}r0WEx)hZhY65_O*C*ftR|Lyb>w;_rZojDG=Oc3X=UIf34>gwZe
z+BSr@#5Gs2bjZuysb@grqFD{TDYAWFIsOsP-z=Ffqx0;FODxCD{3{ZRrE&*<GsU}B
zP+9Z^$!?#jPGUlRsTp>)hF)W!&soNn+9^HveQHnYwTWfR5YAPmUK1J#){1+ZdBUcM
zDeVtw`B3kN;j!+l+K!R$$c+NOZ{Kk+wLrIh4ZOL$)Jk*Mx&rDvd-`GmcS93g!k(%%
z4Tf7TbrA!EL~Faw1jk#NNzOz%NVXc@_b#(wFb{WwC@?3mgReg>AuvCp?`MSCE7daT
zsOmN0&N9=(Ea&>zxZVFq05cCxM?!gfht~J>ut{(Q$T}aY^_N@`k02t&PVp}G*!5gv
zV}18b%a}HdIKgZPU-bjsZUc`DP|xg+F0x{A-Ra+Z+!mk0CH>w+ae^pJ#YUd;1+?z#
zK2BHG$5>s8%TB!?q7rD^OY~!vVyEy<z>!l~3?`LK#;rLc?eI|py5<^0UqAPyFiC^#
z+&3hjZ=gLLbR{2HHlKcbWt7j!QtqEcMZwOA2slD{=hq+{IB1`(wII$d1C}O^m-2aq
z>>$PwjoHCJ@R~zgF!-z=p1Oxrf`5CHcc{nVs*`x%E2{pg_#FK>#69R)$RqB&0*i+g
z!g`P%qDXpvKIPwL=I|y8lO4=Bt6Itx2wuag*hiz4o|@Ob9jIqAC@=}Ux|bU?r1;AU
z{o{~h=zl?IbAB3gk+iWc!xg(2a29SedH8*v<^m30`Iq2_(Sfaxj%JrQ`{rDKb|Z+k
zgarg;N^n?3_b)OS+SjS%Y%qy_woI^vz2_vvOO~FgCoYsTi{2F3qkVd+<Yi(bfd05#
z5!EQ2W$e71&`p<zcSdcwmhVCa1(WF75joC_;O(q8t-X;q<ZQ70s;V?o2WyvusTZOy
zwUrf8W8px_M6YN}9O4PiRJ>!HE)?6LEs_|KJjl`*>Lrz~&vtpw1rS`j>#wHKcu=N0
zW9sDG;gfl@vdg#6*^@feuGdR<cS{tPeAMBn&N9FZxdy>d9XybqIBFa)-F_!>koNR#
z93J_a7l9Z|P?Nc`YA%169%F#dR%V0bQ;Ac#--)sJhEdb}Q&@6n20qVtJo#veSSXHp
zvA*_)*>c!7qQW7K95vC4`6w5foo>i?J1oYRnE@4>h$1m(d9&V(k6x!jNI9CKwG%&1
zerKi>ca8}QZSe2){7SP<T7z2>5V}fW+<8*|OpL!ZXunxl)li%iwtSF(MP8MoZ{N>R
z!J~K-n+W^UlZ{ZKtF7^=H;D_8Dce$OMRgH$2=dKLPDC%U(0Ptq@2o<vS<xEb?&QV9
z9>6Dm2bQ;!3Js$aqBh!rle}$vn)Q{^hqn6G!QTl##i-4Lr9SuwXwpnKN%TG+(iX=}
z#^K8XsO0P6@E<IE4?5%DQTQz{mdv}WNyO)t`SHRj9LAEq(Z|W7WMx)w{LHpu#hU7^
zx=6c)N#iWsbIbe~Qav54l}Kasn>6!^?kVK}1pj3d7h%~eVJ*L}$H@bNXh*xYN6#!d
zuOslV*kzGu(6NS<buki`Yl%Sb+u(pEJt6|HutqS);veqIv6tdkl+1`F%m0p3uhCzf
z>u2ubUQ&u~gjE{~rJ=(^`A$@NVv)bN;n{&}DziIEb<IKL^l^849L_Z%<rEc9=?s&<
z%V;BquiVu9?RV-(<vkNkzL~%iQ4=?m_z2DKzAU?Wdt`fj^A4L<cOV8)nqDTGK^^L*
z_4t=eVujMygxu+pJAq?_NRH%YKMiLazb)Kk<nnCtNi7k&(CA@P_XEt^5}$@axb&<n
zjm+p3hOqCAu~<ZUY%R(KCv&#wWTp!mFwCO|)({^0`vse062fqp^PWKP%d^F9dFfZ|
z2~%-xOayfboPB$jI4Mf(QkEeX!~xMqVzb`{6JU5*AdD-*?bsB(Lwcrs`6nTc66~4h
znwyLDQemJ3+|=01?PUaRoUhBMERBT2%t6Cgb7EBD7g4rDBCR=v)mVnDzkxjFiZ0b5
z!v1nlw9sGf{^+pCJ$^TZxa!S$wqY%XCLd6@ACD%6TS;oFdTfc5S1q`&>kR1a6kddP
znc26g3Qj~h*80MW;~2^)iqy8)DMY5G-!^>tw$V&fu!&KOyQuzy4T(U$x?h3X6;??T
zeSFU1;U@pUoJphY_U?OFH}sN21nF*&bua5YIn`jq_?MYRZ<m=#i*6Oo5A>Kvo58Vh
zR5I3nY4x%tQrA*6W%2OwAT0e_E8fqo2(Us7J=0`y8s0+7kP-%=^bdRT8}+t%rG9FP
z?zc`H>$}$%@QsxO+9TOQYa2;jhbQC!d+;1v?mSgvQ`VUvt|oj>Ub02#OYFr>W+iSC
zIx6i}BMuzb1?i`!Kl2i!p7U58V0#Ve0{pI?FJl>iZ{?aKF_OQ+fZvLzn&;Em(vgdE
zb%`+sfy1T1nG?FRv!I>~DoKjqU+eldq{A4=l^YX(#*gHCg6`yI#x%f{403_9`HLOl
z&mo%Q&!6`PL^7{_F&j26jpZ68Xs8t#d;QrW`&D9-v8wxNoyX>_<TN`z@;uO;A)#1!
z$P3B!Dz}Cl9Nt*y?HrX+rCeBw8iNM?gXoM10#5~-NcVLvm_NlH;G*!5(k^0p(L9Hb
zwrw0q(1+9H_aouolv%7H`=#6W)`iyLYpWGncwD??DIQIXP2QLzv{i)D5aNO`frfHh
z->AK*c*>i*i)zf;v^N^psJANVJycVnd3F<e^dTBBB89VR^|*y|7t!f**x6c=y0|3a
zGDw_#^!=fv9qGVDE_D1+&?O?walog-tt%T$>o=J(Rq0TKc%6)!7Fd<_a}snP%EBZ@
zTswA5_Qi+!%ef3!yjFk!cxPp`w{tDtAlQ!>e2;UOF9z#-xKe4-wVatLw9j|8RnPt0
zh9-(L0!Hsqu%wygi0$^!Jr}g&QR18H=vPf8|9vV>b#vef<a+#7T2s4Om+L<qlb)N{
zbsS7a`wm&HvlENbm2j-o_c%oOoS*_C{Q-Z+QXMSe`@_=Pd&_Uny<}HK5+QEX`T+~R
z1%>mVTO)nE1{H5xL^rKS!vkO(bpllgi8!)mJ~R@tKTKsT8WZi>f9I2dF0JFEBV`Zj
z<$bT8{UawC0FTJcwsW(I%!NB5E^=)@sK11ac~Bv}+g$!ACd6<t$*4VOdCIzS2(p{m
znmEsLhQ+Jk;v<fKaz$s9#RwaRx~vP+dfxl&|K&R?%z}6cdqSWiA8Qlx8ON|5ePlXo
zmFK0iT-Cv|lnFfPcBhoTo)S#NZMc<JseXx&t|5BR)4;-pifCPb+hhqsl#x5iC(4K|
z1D1*5@GLS2C@d4=PZHhead%)#h%I1>+DCk%^ghhOt(+dE$p=R@Rq^+xr}}Chs9U3<
z{gqt6x8+~W+flIW;i==4nNr4Lcxgv9Qn)TFNly08_PQdx&@5h)axM1%kcyaLi)bfW
z74f?v%KEVH^lz#(O2vMIm^;JK%k*8dN6)&T_j}2Npy09_xj1Y17OMD;t|gqXEd=5<
zX}$m`y4##hcSzFVBzYL8u@X)yt^*Xldnn;E8pRsCO{xQBjihpVjlfCPPq{y-%`S-1
zJ+o*B0>nRylCw?o|7J`boic_D>bGr2>nEcxFjjR9gvuwL5^`zA$-E)s?bfLnHxZpa
z(Ne__dDP)62!~P_MK=sEvQ&Q*zyxON$(S<xeBNTjvsp^Ju}*zh<;apa*+9**=pJNC
z<uskQIlWQv6i|%dEK8gI0oIpC(q+gLNIV@paj^veg+h;Bd@=tMb;jiAAJx=T8=@Sc
z43DQ>1V3TCwd`2eT}@yh3fTi3!&7n9_cRrQ;;MBbqPCNnpNBrLGVsEL^kHls1lL+l
z`ng9;fLT@jxZ#*ptUUi#9I2v>@c>}Z`yV4Pw2Mu(4Kh`T!ozbb33-cPb~*P^76n-|
zXRyR*uZ_=-AHrt8S7?V^Uj(FpjT$<&M@>=q&yy>b2gsxWIWy$4yF19w#!I!57FPyl
z!RQO(EEhphFpxE?B4f%^Lx87i*(W_fYyy`u(&Sz~4oXj<O+xwnn^fKk=gt^>Ey>Vv
zNR;#pv+9K`teu%x>Dp)(J=QB(n2COM{w>~`o$1Hmz2`f2H7#$~yW8o+ny-+E9piDd
zn1?GK?;Azyq3_XbTHRaA@!ENF>^Qa&WGd%jq;2k8O^~10Ax|kf;e7I+8sP_yZhl?&
zamzWVOTPByom03prjUBz*ZZs_1++aPn^`*$1jnVsO}4O)vE7k_qN6o<!z00?^C{e!
zOD9T?A5sTKx|_MP@N$Ez7wFVhNyWkF?!tVGfO$iWY@(BoWWGx9Npzk;i5RO#V{4an
z^iidk6l`Kngn(^?hljFjWaNB&aork%T8GBYT7byXxJ2C|9Y0t46e>4NBB|L|uMo(`
z*@bz+ykUQVQ7#K>H>&%~hosCZFj%rP#>gM7FBjhATuh4+`ZOzYmbp%DfMImZwhNOk
z3Y#GT+skWIx}-+gT<;CGXQajwEiU*@=mNCQAEMIG7`86R4LCbd9Pt;>Or=o|=!2T`
zMxJ9xs|Cp!vVl#AM-IEg(=#^Zn`@xb33uc>e8V1}_SkZ@hnl*_868<Dn1$)f)?2=_
zCy!I%6j0`#SJFW879y2b8?G4Pmp;iR<(u+|!E36eCgnAFjAdNX2c2}E<9GE@J~r4|
z$|uQkQc)5^HojtPDFmIZE?&k!tWBc+yRlz3aO97T<yW59E|ckDd~%&xRFT@O#98;I
zLac3m=uF783OX;}i{UTEYN#)nDgl(CnLP%RUrB<ROdBlNsL0HC-1TJM6q0Y~KFfMl
wovoi%w#&V-F|*C?s&U`ue~XvP=&I83j<8_;)Y7^APlWrwU!p%TUIXxd03Yyj-v9sr

literal 0
HcmV?d00001

diff --git a/web/tutorial/timed-lines-2.webp b/web/tutorial/timed-lines-2.webp
new file mode 100644
index 0000000000000000000000000000000000000000..944d66ec817ad76780074fdba3619cdf98c21af4
GIT binary patch
literal 8714
zcmaKxbx<75xAzx!clSVWhY(;F3GVLh?gV!yc!DPccUT|<OK=u<cXxN+%X6Q)^}B!E
z_dQ*G=F_LY)qT2WYNlpJO;$<@mKFfe{v@uVr6Q<<3IG78-)cAvpc4R)m5@;Bhk0uP
zVEX^@@SFgEqmzf5nzT5zj;<ax(mDX<t^Bu{n!CIFOaG^TQ{B$~tDR!|KNbJ~Ac}>h
zyZM{s{H@Zvy-og>6aE|HTmQ>U|FGG=Ec_39d$@SKX;l7UHw`t3H@0|VChPyjX8()L
zUEKcB$G>TW9UVOXnd=|>XLab7PMYd(N94Ck4sZvk0i*%q|E&M5{btVj0D#~P005Wt
zpO{%D0Ps5k03crcPmDef0Kf_d02;^s6Z_AexR|<`{`YY3Zywgl3IMn)0RS*`0RX&l
z00340zx&?Y|06f*w=VLxyqw>PHNXL237`hZ0-ONm0QNWH25<tn0Q_%fm>U00IqnI_
zg<+0>=>mw#Qht%7{rQuKgusRgKD_R?OH(2Mz0}H-{U!5h=0-IK?z-lw{r1ee{n98;
z1OWVX1Mmd|#{1d@cKCA!4g?PPeK=hBEbxG|CE#Z~1|<R31?}DhU0_8920d`Rv_rky
zj4zESZ(H{{&d*ArTCeS|XfFcy&dY0Iz_OQuM~O4K>zd)jV2<AQm>~JrnkW4izlb<d
zDAr5%G}?4ca*+G$&{No}{wUAI*ual9XmUIGtMv=jrSr2g6xxBc3GIj01UbCqzW#zj
zUy-Jaw}Bm>ivzTufzOHO?EoqWFf+*G_4jMsE7iR-6nYEA0cu0FUrL^9Ue_*PhufK7
zTVJ!EAdk*3z@4`NV1uY%onMWgjNeiZ+5keKXHP$GTAx&*&dXaj70}OD_5$-_Cgw=5
zwmG5extz$t@$N|mc*QVC$q8<-vnB?tMiA&07BE(#DVlQP*{e1BPShuM?i?9=W(kHq
zu@vtXt)i&^{cFRnNa`%H^ZLp|FN(V1A!*+*pBn7|D$=f3rSl*0X(4z|qOgTQu09~f
zI#=X^ha3u$&aViN>ITyz7}F8E?KnjvhwQzCmxLj_Mq8iA%(oAbse%T$Du!MWxIfpc
z;x|4XBLm^6pH!p?PEExXh+0%Ac-1yRaKwZciqs_3KW^F5%!5pQxc*vy<s{#;C;>V3
zaaT+0vRo@40xU1BJtV@IfNnwXae#04N%Lf22;9nd3hU30+CO*Z-ItHez5jIN)~A^W
zjA@NPDP#TV*ImFge%Y6m^U}`k5)s&>c~USe(=aW(cHZK#404=qC+i?e`xNO^HiO)1
zQY2^$!1vzc`qRYW*1*G39%-d(k<t;0&k176ZIB(UEcOyQRhvDF{QLU?2GrndO*WUq
z$UUsge&6sGyssQVa(DR1t&7IpTdp1x$B&JNW2(#pey-tagG_x%^BJOQ!TRFAy8?%O
z0}l^0a*UReceb0Az>*MOHKx>OF{sISmGNk~oZ1K8x*r|{{Pd54j;He<aa+*fXVur0
zaZr}2R(^!=D8RJqH~=cu4RwBAFcAq-I!16dWP<jDMu|7|Na2OF&%@ZSL*mV~B&=S=
zw$1<NLNGqxH8P$j8Pg&T@M~CoEZSk{F?nzq2R_SaW57YHQlp$`Efa3JDZ?@OCx63U
zleO$={iPeUkHm*YIfnA}i%T>Nq;Qrze{{gf`K;%u|1}caJDU5?Mq5-H@M1x63A#bM
z0Kn_y^@Mm)Y37<_Qr^DbKo==`=;2~GgomA8un{%K^o0FkcTux$=aWZ*tKY(JzfaA>
zg3J=etltjS=0*ps>X?*zttJLd$hzwRpn%>!3-pcApLbdk#_$r@0pifkhi@7$QKysP
zUi}NxW(pxbiPvp)ZHyQ7r9GLjS5yZ+mY<cktW{&UG5m_ZQVx9%m2Q#?dM*!%nu}^(
z(AhNA63A^~vumsW9rW8!R^WAEqDVaIs&bxzDk+>Iw9N%O=zQ}&y0BT$;m<-yl$Mxi
z(D_qTd4387>_N(iyFxkaNi}}NBVbpp?WLH95-Q&AH;FhX%xIgw{_B;3S7eF|A|gt=
z3ljhO&Zl;<Mw7RZC$nTwwKE~;6~O>+d3*tR5}=iiH*m3Ku+Pc7;42J$-ZDNq*VZ1`
zY5lu`^HO-Y#$EM9>KnTgeCuq78w%=|A=>3X9DL>`PNj~At7c^4CQeXJCF<;$<@`LY
zq+63g^4F{DASBQpJm{YpO^YmTLgZAP$1I8Xz)0nBmT5W9;p%{;xmwINdvqIW7BP#T
z7Y~_ntzW0xE%-gL$jFd6ZFB(In{=c|8p>fD)@_WCBVL970A@#YT!;?~mLcN5-I$$_
z_&c)yV+zm5LBFS#X875oE5!fZPjfoD5~Dy;S;FPUE(tXNE<kdhZ=$fxWIa&J4`+r>
z*m`Plv9|h&sbw}hjKa*Iep+?`E~k%9EY2Roz(6nhOUR!u1p<7q?{3>0B1+}92Al1u
z-36$pHtK?KBik;t_-o%~n-c-X!GB25bdAc}Vs^IP?&MGUt>WqmXIh|-PgY1og6e9#
zjUl1=PbRO629~;UZtEOJ?@E=mR?lehGmUuh2oLLmEq3$m@38m>&QjA5<9Z`C1O<Ou
zc*6dq8=S!F27;Wiiqs{}3zF9#IL_s{)~X)VCyGpv>$<ls{ap45Wu8vhy2XmEeBY6n
zt@;WGzeJE9?4Wv%vUIZi&ibbHyy4Rm4prBhSwh8Kb}Z_S4=r!rzJ&#gOt|!)8yUwk
zZ;(-Olr(ovx_N%)Rnw(jztJy4kmHYpQ+8Z5p$o*>W85b7Z+?~P#E7q#GU;Xr5LzQP
z+-wft`Fh9c{v+R3qW&1yic9~BymUZxts^H#xWEV-3CeP%_`P#-@lunaL9^R-*X&E!
zxMZ2(#zLlzJLRaecP?V9e<Idiruf8m6e28U+=Im(S4IN)4S&;!Z(q$byU+?HwQQax
z_MpYASL_&5CF&iIc-xZvzIg8zB`cMa_A|1R3vnv{(_<~yqzxx&$j(sd?sqk?R-+f|
zYgi8xMZ8%awUSZ)=L)VDZbu+S-2+fpXP(V+P7QAx>zh9SRj&;0*AM&>Q?z>4XX!+`
zAak29S~bN6r?@9ic9In8Aj-}nTAhU3DF~(UZdGIqfm29cs5KYzmDM-2#24O=viTTk
za_8#Wk_J&$=u(smFCVEhp9IaSbtul_a@RFPS?`1JZ52gDS-y(syF`Wy5}qJjim1U?
z3;PR&9P0!v{fPP<@QSLn+Y1$ah1VRbFfrs6+RR}7gxgUE>em6W@*Ml>d**P!IDc1N
zE1LE@ThV?m{^McoS@LH2^zkVvZ?OJ;f{NGpibN0i{0=B2yz{t(<Y%0*0D$!KCI>2f
z%;m`Gs9@n4IQ*EMvm$oD994LoV9dRMcV*0`t7bBK=0<YQ=95hyveR2`%tRg#HF>tv
zA7X$AVJ8jggoqXE>_lGuC3xg4%F`V$?YbFhlFBD|8b(f`DCnsznL3!mlQR$Q?g2xx
zPQqZH(MZ@9SVXz~LoR1NYKUJh?B&OaAi+<^YuH<)Rm^Xz0g$KfVpSQUU8S&EJdRA0
ziwpk1zXUgyK7FX6m#_4Lq(ZbK!sB|~PDtCWu%;mx-MB|IPvb62AC!PB*0&9t$PnKA
zNimr#d4mpf<b$<b8^GptAwT2?Onr#YY#Wi}ms_$FX->WmaTdALR<NU-0VgJA1u*Er
zQ}s{Vo<bn`YO@3dE3G8~O||!JH>&kpNmM;^9lhkFgReu7Nn5eojYL`L83dPO3%{Nf
zzO?~dn1z&e=e=@*v!3taReYZ~I!>JqVlrmA{VVO7S{%(k#GByNA6F=-|MXzmz)m^Z
zN8_J>xip>)KsZVi??azqWoJc-JVqlGhMXVb9!8*O8iO;fcEbo-=82kc!#|9tg`Gw<
zw=Oo}Mq)a;jUzlcm=Z)g%PU`{`1ZEJCk%}lt2XHb0igAapl`nN;?>PCEFRXGyQEpg
zD>i(Urk~Q6RsLoH88@+HLz=_#xHrM;X}LxvxY%F#U=I76_y{eoG+_@$Hj4RtZoY=s
z#)duHD@rN+0Z#&Y$b+L(KGj^GIp{z*aI)D#Qb%2EtOhnFa_nbE)?gMkF6cOm(tZih
z7H6dmFjT)Y%{?^QH^MJYFZ$y(#NkwYoEW>PG+7z>=(VQwJV;3qhcz`a#)Hg#k<<~-
z=r<Et9JJOb1*nyewNr(0H#nUV7wixG10}8_5%?XqWe;s8h(61RXe;aIE?Fx3S_r>E
z>YW->s|~Vza#mJ|0*~;F6fZWG+yMHE4VvkGy)?>|SDPcKeYruua9Z-XAy?I|O?&3<
z!5qF*?nURfdwiAh-TsK)fcAMfj;#bo<lXX#9^XsWQmtNxVH(o_(EjZ1JkTB=jz3!M
zur79Lu!1zH=Gf_(L&G<Tm4Dz!2Zp(@W4knscL*DQr3d1M(s59MR8L^Q9(K!Mv5CY(
zW<EJX+-e8ToR2squz6+bMb#_>OO8h~d{#dm+c0d*IbpUbuR9)Qk*LRH$gyZy!!g0E
zvRA6OL=j<1sJ?AP^9EqdU_m{uNTBR|OBpF5*ZU-6+0Glw5R~cD*RE9nO<$C2;uXpM
zx5BSW>Bp*qw4%ApwWItQJJux(b&V<`<(=YMUtXZ++fpj*idXx#Ji7)-4n?f)D1C&{
zk^H4hwx7}!7PQN#l1Qp+E1%klUvh^dtE9C#emxj?ai0-5`xH`mY4W@*mH4xDl{0;k
za3I0-X6hqF!wfXq6zdECB||s=W-BZp0_}zpZU;9AjE+=%T@Ue7_GOh&4^|MC!;abb
z068U5THSNv{S@fgU0$OLqHvk;<0`$y$;BSy;pdy)MO8NbmUHbuR7_(tlXo~Sh@JD?
z?tX&bM~a$v`0GR+I4OT444DJ5C(|aIs&c9Gq`*Tzq7OeyJcnS7sAXa8`XKnCBXsq!
zI$+ca4WR)iMToWI2}(MQ3fe1gm>J?}+{kg~Ql6}8R&E=~ii~1$I>(Hp(+JJwGPG5-
ziFaU`zrGVj2ek<FpbhJ6e=(6Kx#y{2B*GpM{1oz@d3zmzOIvE)Qde6z@bw6_DA?Fp
z%kV`G?AiF>ZL`ve@vV42_&N(W4w|nfzm|;!)`$Db^m4=vF-n44ZgHjY$gQ<sl>A(p
zKmMKx2+PiXn*K9dveDoMeSx7ts)0VSI9Kz>g{Sxs|CvAt6<@*J0?i`>p+k&jmB!M$
z4Yj*i%$gXsiDds)Oih=^@!Q<rSkwZsP59^R29g;*6p`S>2eYWHod{vX%8$8o)VXMT
zOJ7*}v8d{r2u?&YVJ3^(Mm&}hxl~I3cF9A3XgxJHyOqYt7&KvC=%oyCTw1G2@S|b$
zWmG>pPmLNgl&5s)@#cphaSI4Vxb=Es?I${389g~E-Gq+W$`E5DGBuPnEBR4#bv`Q4
z3k~G$c#z=JvzZ>9YDPRVDokLLROttG7_F$nw|YHw_7lX;45M?}>G{o&eP+tW*w*`U
zITn~4zX^>hcaW9^pWmiW(rht%rsrifQRp2aq(c~s3yg%X4~skv5;@(z(@Wgal11~5
zH{~;-#FF=TDCGyG#K7LAJ9RR4LA)&^`6Q{RyOlSIx~4dnwWK>HcV}JZ<h&NVoZ>7K
zlzzb~xGB#3roGs^P_X{XAVE07hNMf}=eMi6lLaN0844mlS(r?mK1n@1x03uBE>jL$
z91u+z9#N<{W-U0njuril6rr#LubC3U?MHbldYe?6bhO3D!ns<1UCd!~wU-u*7zw-9
z@ihMNnw^o;&f}K8e`$COHY*+KCD9IgM6TwH|8DO~D9<S{AgxL;Y%^06t!w$Ja7d~U
zUoK4%#(S!>rXl0=<=~k8v7EK0(6BM2%;P}CWuxq@6}8@1Wp^$@*<Ur|EQV1}Q$Snd
zOAkPwqC*{7jms}V|Ev<BVs=<R(iCZz8|&=@0%rxkOwZ!tbvmZP<5OH-U5?C83ARr5
zgj;KeMymE&p<U|3ZaE<zf`$Zl^jtcxBo?|XpG}k+>2W#4tZDr3KOA%Pac5m;16$yT
zQxs=FHeU8pU`8WN7%tDPM-N`>EPqBTg&9+cxZQ?UK^+moqs^w$)c5tg&4;3-@eewO
z%B)Or@1r~@BB%#C)Ah(y<<NRV;SR!TV_ydGk0M+JCBfQW!aFdk3QP5M`-1yUlChRA
zw`fY%GR_=oLW=K%v`W}fL}Nd?O_L-4U>%e@oV;RcE+@0SOBl>O<n}jfIq-R|=etjs
zCac_c_eYZhmQ3W7Kf#5&TtA#)v3#=_sVPfISs(FP9blR=Ub1k<em?$Ib~~#an`uYY
zXn&YcV)xCe@WU&$1%|mci&1_$2e@cOi$d$w#=B=p<DsFnsCLgUZyqZ9Qd7ATa*uYW
z3@Y45lmLdnO}NUeg;0XO)M0?+83vGTRzR&WOT(E0qiUqiG8u}cBr{7Y+D4dJkST&c
zPTqfRS`JS_y-4ww?d(jOS<u3r#jlBxA;w;q>#lKkE2F>&hn)i6UF}$U|AvPbC-ZqL
zY$;6g&H?2J9)Ko^jhv)s(TkWNg@yQ8k-TzgRh)HdGlVa?bh!B*@O<3oOV>2;!?YId
zc$?nQhV>%aG#H6mYQk5l<@6n;Y7#7cnX(wmswZglFu=bXoAYC_Z0#JAEe5g_;aE9e
zX=oqaRu|>Yz?LxG@_ado6|BQ%+Dup=iO_=70(yFcS86O(u7{j&&R2g`t7W!O3$Mg(
zy{X)jlzVTAgE3Qo%?#AiaiklL!=cwMrYy4tolw}}{pX&LQgT3Sn~H(pPz4?dV~)pg
zCVxb-B2OxPfI!aok4jD)geX38S>oM>ABH0QLvd?2BjONELl-xYv1n2(elomvh8d72
zJSGp&@++Aw!-O$&DuW;SO}~HT3F>70sSu0N@l)gDwR?fW__()tp-^s38tg&|{v3v~
zdp0)fu=nbU-_FXPNvT0YpJRFa@wlR<7JtWp)ainJgnowzvXd0yE(D%#@H^k@w3!La
z`()xNX*f{6at0aI`K^!pA)1|JKqm9Ao~%F>mxVtLQEVMCXfP7diJ)`Zo-ge&p?zj@
zl66@(OTVb$f#716oBpkc!ZEadN8STy5k#_;p18Hw)ErF-k-Bizh5;Pk-SY*-9PDnD
z3!U{nNC<>y3(aPBUjqTr{D7%>JlG8+zH6w~RZe9qD&L8Kn(ASdk!gL+d(tz)oH?lx
z`9)xWq(`V9Yq+FqbJwa6Q8Ib^k9Swv%`x$>UrX%KnU_RyAQWmySqD|}gqL8m@+f5Q
z(O=Vu)fimg;i`KtayYL^f`ZAO!;AXZynnI`kuLD~4;8aD%>w8@sq|lO7Zg))-it3U
zXR2z}^%jj0qN5Nw_}OT9Whs7O72nfItWk_PQ;D$<Yc)wK!!cOHW0q(HtP@cRd34bm
zVAcg>uMZ|y3Nly`U9@Tk2AfpglugRfSbuu1n89TwTDM#9Nn#2Tma@M)r1|O8;}lP^
za<_H)EA@E8%y^9HD^PB72d<^}T${Yr;}Q)A4T3|z_v9N<#PHsE8d3KgM6cs6I&Fw6
z?HMJo!(?)@*#P)6d{okqNGTjG%NNn{fPk2pr(VoHMIMxFz~q~yG7X-7%#q4Y8dQHr
zv4e*@6|uH@FYY<%ER*{QMJ=|;I1Ed$muH>H^R`bLv-dA`BV)iG%f>c07WRR`xt%6P
z?qNPxo@>BKg3PHntj$bjowk%2tFoe9s~7X_wV~M$=8YD*V{Qv4Xgm*RI!#2aP-})C
zjM!ik$<kSUWzK1_7#AzeP%U5WYW${7;ti@84Nu}}QfpOmTx}^DUKGvD(?Lnl>56gA
zf$ynkb~5QTIo@iz=Jc0%dla4of5dolFy7K8e4sQ_md+6U<*?8z=h+fm@D6+)lH@ZA
ziAG;EK_C98U5w~Jw2-eLjvR8DSJYi9;a+5ch7R5&J7FOx7II7YyY*AsP`6@TPg>+(
z6Wg$p;@tqqHv$-5x#L*1(8tvEEsB-hst*<DQaK6OO4bQ4ORj4%69Z7v(XscFz8-5C
zA55z6$db$ha_z6kRF=+kn@1Aj**SE{9=u(zj_3MLjVuB4+l5oO++-J&KI!!@*w|Sr
z0&&AYc|5l9h?c%#VvPgNXg<xhm_9D7<zSGuXT31<WR^FfcDx3=@#TF&2Z5Z3aac)Q
ztP6)lKdxO?^f&T3nPjnqhf&EZY>Cvg=5Tp=F`L*)&01b(vfN=+E~o9^lozmzLG@(x
z76^iyX+AAyve2NMKH?<%*pHHtE5~GmLV*j?y=2A-1^i)7cO)x0(cP(#B)?Rj%p&3v
z^yx}}ehfIs*WMM#277Wo<wnK(3@$^aw%?h11$5ieYj!g(3a#3~I|-E=(3^ZwB`<Q@
zjKn--0Vb$1sR$D7qMqu|=iiSAWSc~UI!ZnO2y+0`x^C#m7`dy#DITrxuOe==L>v|r
zQ6u7)NzeN}Qo|t}B59TzF;~YvMGJ782}1vSdctE>erG-<D%(#<+FDac;DGqa-^jLy
z_?eePVHx39yZ!Pa@w(;*`|jQFBIh5I=KFqj`x%Khm*C!c^*8tx#T1W3>ma~>Rgd3_
z#j|Rgya_PCI|A>IM$5)?m!{<EGC&Z7Q!T$ysG{w@9G9{U;cGjgyzd=Rf5zO*dX7vV
zu`jUAIU@A(Wt<F^sE*jKyud|`UO69ckpc(aBmqrt+EU<2B_0Bf4`oH9ytPe2m2t?V
zaboQWVDZ*m-Qj@j{$yk&2HJfP>jKCjyOmLHmy3J&O!3JFiPl=FSW0}i?={8kq#V^k
zUt`m<kqhWF0LW>7*dER;k3KG_w>n?1jd$MBd{?0z`~pk2S3NYWz3mP1ziwKZ7scvf
zyNrXWJ3Xa&0+7)sWfUoaYRtT|DnHF@`OL<vQtTYob_1_xdSkV7;R5fcD2gpuR>1{-
z{s!JS3Gw22s<RJ!M5FVko~Y>W#K@`kBGW9if0LsRzOm}$;gn~}>M5VW{*4Jg_bBx(
zpCUF6OxV^DY&@RaDl&X)^j<<;Aq62aMLM5=nHE~OuI5{D%}*1a7LnMfPZMAT)EB#8
zTBOAvFBz+hK%7|8!TK<HxDcc*Nefl?G&NTE`vN|CX5B?k4O745!c$^YTAopkeKJQi
z8t0H;#;`@I-kc?%+G#g71#Nr;ObaO0Sry$*cGq+M&l^D6bNtLg=Co~(XxrG~sTG7%
ze4rJXjqhZPUNy`YZ#x*p;%iVDBki<n>Vo}BS(v=Hz~jN;+IPh&mJ8iKH34hfP0Fh(
z5qwRcb^uC_2Kn&>0rk<^N+(jkj<w!lr$#>Mbtf+E7pJVmq_g*bD>FnD7^ivii+qZ7
z*A0HvmdTHtb)RtWQMJxm3}&AYG%$B$&AC6DD?fY1T$wkZZ8v4v_8buo<~3Ng;TTzE
zqri%6tE3r8Vg@ERf;z{;u@s#D=7>>#l$Kiu)9UVn3$zNh$b5F7d9QXMfxi0kx6jI-
z+V?+*A+pbkQl_eGF;NlCr;y0Fer+Tw7f6!(PIxhoj?02mL%QJ68IseYM_p!QB4Ree
zRe`!44)5`B>BftkO4|>Srxf~$h#vnS{!Zq03tiLYOmz5h)c05PtX1NRkCfD^IOi~F
zR3Kc8?6-tYn)lpWgB8jcvO{ucJLxssCkKi2n{ZwaD2;wZqK<LensbKt370-zL4tOb
zzm?cPaGR-oPVocli49#U0z@q(54u9%PiD5<$FHYI_v_`b+Xjj_C{yI*9Uf1j7jTzn
zCZYwc4>ki#+FqID`(m|UIx0#T^THabmFg=U#|-8<H~P|0{arVyei+6RMW&_9k=1MB
zDJ@R;t0CKDps?;Va`RN8*?v%XOx<E#xN%hD(CF_TaQvgJThiUll}=H{y=Txq8aoC2
zbqtibEzbnWz=#ekVa=Ndw4Wx=DEi`LRG*mW6DK>|#BB>J^xx=<R{7i9Z5e^2RviVg
z7f)kG55uQUe<PW^{)LG)Et(7XsM>nW1k~fl(oaP7b%5&7{-q8@V0vda=(vz`QGw#f
zGp@;erXCz~WSL-2dZa`5NlHv7+k&bnJeXG;e<rZdF0NXl!`WUEeZqo1OW#Ey*YCcx
z>eW|um9|4Lyn}}IeRnWelfCbK0o=V|8Uwc~!WP^C?Ai1dsSDe~ga=QyNfNc<Fq_t3
zeHcQ-XEdq#u7I1GmT99oDb~Ttm(FiaomG~5yUkQ4CPfuts>PI&SeS5San0}#c)Mbv
zj4#g{TCA%Gq)yT>TM(il=69|7DRSjWh_#~iu43l3uk6R^fCk|TbQ1{k5y&-+ho=fD
zfuU>D>P}Ih%iW_$D1Y@2|HD~8-rJKm1c;=qY;%gH8M|Ro@z|W`%+2VS+DADCy$|!b
zYopgdye^ksqUiu#is{T}HG^P9IQr|7jw*EHoA7t8wzdY+LOGNE%rE^VCVE)p3*?5i
z$AF2~yYiM`FtHv0gLV+wiHvT<K{~?Yh$bosir(ACId*N|`vM$zRF$w`6<N)k^|_Zg
zAAy=(u64||YHE;P$_tV6Eg<WwML-C&oJX1#`v&uFg%1up%I8YFR}Y~{-^h-(sw~>1
zlq)BHj=t5QRCp|7Phw~}^JiA@q=*>m!rF=SAE*tP1FQY3<n5o2C)z-_f#*%=;V62^
zi|`;Uq{JC1pe9jt+($A1qZFQ`-lZ5_6e~QFw(P7QOsJ;$fn9wldpvCaDT4cy>!Dm0
zM~ua{hDR`-GFWsSHZt%hKTukm6D4&6uSufdmyeJy1J;c^;8v*wir!_z8BUjHncqYD
zc{(9^Qb=0nfP${j<6m6&m6qv|K?)AFRl!b97t*j<gUj~Pq2`wD<{sk>Xr1!IFYotI
z=gP#`juU_Xd1FYr%tpvCbF9ztXbO>xr%W)8@UMouJ#<Wdmi2CC{G5Q7iu@+s*$}_|
z!AYPDaXa^qpXe=z7Pqw5RVJT%e$7=wK`sD8;~w6_O}^vp*E|hV*QZh}JakDK<WR!-
z&0m&(L4Evo(sdi)m>jxlz3+6ZQlsTKOB|~wXULEmDFQg#4|v-Lm~>g6UmZ)-6;;2o
zzsHo)(y6G!ECPLN|Io8}b;qsWK2c^3!)QARF1g~p;$UQC)SE$paY7Z|-i@|jM{u{N
zv&Y?N2+3F@AHPi4pSZ{2(@{)dq=D&*L7-v}MyH7-Zy>4sn><Ve&f?Zv>8Fj{-U_O$
z-F;L_o_oog;!rJVQivMyI=u0};l_Jg1I=d;d{KXpjt38z!PJT9<hosl)9by6s*|9>
g$7Hb`&srQ47@7fHyCj<9^As`naPm7t5a3_?FaB<EGXMYp

literal 0
HcmV?d00001

diff --git a/web/tutorial_book_content.js b/web/tutorial_book_content.js
index 36c7261e..2642c276 100644
--- a/web/tutorial_book_content.js
+++ b/web/tutorial_book_content.js
@@ -47,6 +47,29 @@ export const TUTORIAL_CHAPTERS = [
             en: ['Higher resolution and longer length take more time and memory.', 'Text named in the prompt may not appear exactly in the picture.', 'With "FreeToken enhancement" on, the prompt is rewritten in more detail on this computer.'],
         },
     },
+    {
+        id: 'timed-lines',
+        title: {zh: '按时间写台词和镜头', en: 'Write lines and cuts by time'},
+        summary: {zh: '在描述中按时间写台词和切镜，镜头会在写定的时间切换。', en: 'Write lines and cuts with times in the prompt, and the shot changes at the times you set.'},
+        media: {
+            type: 'image',
+            src: {zh: 'timed-lines-1.webp', en: 'timed-lines-2.webp'},
+            alt: {zh: '创作面板：按时间书写台词和切镜的描述已用红框标出。', en: 'The creation panel, with a prompt of timed lines and a cut outlined in red.'},
+        },
+        steps: {
+            zh: ['在描述中另起一行，以“分:秒”开头，例如“0:02”。', '时间后写“名字：台词”，表示这个人按顺序说这句话；直接写一句话，表示这时发生的事。', '时间后写“切：”再写新镜头的画面，镜头会在这个时间切换。'],
+            en: ['Start a new line in the prompt with minutes:seconds, for example "0:02".', 'After the time, write "Name: line" for a line the person says in turn, or a plain sentence for something that happens.', 'After the time, write "Cut:" and the new shot, and the shot changes at that time.'],
+        },
+        example: {
+            assets: [],
+            prompt: ['A small platform at dawn. Lin hurries in with a bag; Jay stands by the bench.\n0:01 Jay: You\'re late.\n0:02 Lin: The train was delayed.\n0:04 Cut: The two walk side by side to the train, tracking from the side.', '清晨的小站台，小林提着包快步走来，阿杰站在长椅旁。\n0:01 阿杰：你迟到了。\n0:02 小林：车晚点了。\n0:04 切：两人并肩走向列车，侧面跟拍'],
+            settings: {seconds: 8},
+        },
+        limits: {
+            zh: ['时间必须在视频时长以内。', '没有写“切：”的地方不会切镜。'],
+            en: ['Each time must be within the video length.', 'Without "Cut:", the shot does not change.'],
+        },
+    },
     {
         id: 'first-last-frame',
         title: {zh: '首帧和尾帧', en: 'First and last frames'},

From e6fe42089998cd137c2b5d032190d22ff80b9139 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 06:09:28 +0000
Subject: [PATCH 02/26] Linux setup: build GPU acceleration with a private
 compiler when system C library headers clash...

Linux setup: build GPU acceleration with a private compiler when system C library headers clash with the toolkit

Newer glibc releases declare rsqrt/rsqrtf (2.42) and sinpi/cospi (2.41) noexcept, which the
CUDA toolkit declares without, so nvcc rejects every file that includes <cmath>, whatever the
host compiler's version. Before building Sage2 with a system or versioned compiler, compile a
small CUDA file that includes <cmath> with it. If it fails on this clash, build with the pinned
private compiler, whose own sysroot carries older headers, and record that compiler in the build
record. Any other outcome leaves the build unchanged. The probe result, compiler and glibc
version are kept in the run folder.
---
 freevideo_engine/bootstrap.py | 37 ++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/freevideo_engine/bootstrap.py b/freevideo_engine/bootstrap.py
index a42794dd..e9f68f0e 100644
--- a/freevideo_engine/bootstrap.py
+++ b/freevideo_engine/bootstrap.py
@@ -415,6 +415,12 @@ def host_compiler_choice(below, path=None, env=None, find=shutil.which, major=gc
     return None
 
 
+def pinned_compiler_identity(spec=None):
+    """How FreeVideo's own GCC is named in the wheel cache key and in a build record."""
+    spec = spec or json.loads((PACKAGE / 'gcc_linux.json').read_text(encoding='utf-8'))
+    return 'conda-forge gcc ' + spec['version'] + ' static-libstdc++'
+
+
 def existing_parent(path):
     while not path.exists():
         path = path.parent
@@ -1907,6 +1913,9 @@ def install_sage(self, uv, python):
             build_env = dict(self.env, CUDA_HOME=str(toolkit), PATH=str(toolkit / 'bin') + os.pathsep + self.env['PATH'],
                 CPATH=headers, TORCH_CUDA_ARCH_LIST=identity['arch'], MAX_JOBS=str(build['jobs']),
                 EXT_PARALLEL='1', NVCC_APPEND_FLAGS='--threads=' + str(build['nvcc_threads']))
+            headers_conflict = compiler['env'] is not None and self.host_headers_conflict(toolkit, dict(build_env, **compiler['env']))
+            if headers_conflict:
+                compiler = dict(compiler, env=None, built_with=pinned_compiler_identity())
             build_env.update(compiler['env'] if compiler['env'] is not None else self.install_compiler_linux())
             if compiler['env'] is None:
                 # The private compiler is newer than an older system's libstdc++, which the Python process loads first.
@@ -1922,6 +1931,8 @@ def install_sage(self, uv, python):
             wheel = wheels[0]
             record = {'identity': identity, 'filename': wheel.name, 'sha256': digest(wheel),
                       'bytes': wheel.stat().st_size, 'build_run': str(self.run_dir), 'kernel_validation': 'pending'}
+            if headers_conflict:
+                record.update(headers='private sysroot', built_with=compiler['built_with'])
             save(manifest, record)
         # Install from the verified wheel path, avoiding architecture-blind source caches.
         self.command('sage2-wheel-install', [uv, 'pip', 'install', '--python', python, '--no-deps',
@@ -1929,6 +1940,30 @@ def install_sage(self, uv, python):
         save(self.run_dir / 'sage-wheel.json', dict(record, reused=cached, cache=str(wheel_dir)))
         return manifest
 
+    def host_headers_conflict(self, toolkit, env):
+        """Whether the system's C library headers clash with the toolkit's, so only a private sysroot can build Sage2.
+
+        A new glibc (rsqrt from 2.42, sinpi and cospi from 2.41) declares math functions noexcept, which
+        the toolkit declares without. Every compiler that reads the system headers fails on it, whatever its
+        version, so a small CUDA file that includes <cmath> is compiled with the chosen compiler first. Any
+        other outcome, including a probe that cannot run, leaves the build as it was.
+        """
+        probe = self.run_dir / 'host-headers-probe.cu'
+        probe.write_text('#include <cmath>\n__global__ void probe(double* p) { p[0] = rsqrt(p[0]); }\n', encoding='utf-8')
+        command = [str(toolkit / 'bin' / 'nvcc'), '-std=c++17', '-cuda', str(probe), '-o', str(probe.with_suffix('.cpp'))]
+        if env.get('CC'):
+            command[1:1] = ['-ccbin', env['CC']]
+        try:
+            output, conflict = subprocess_output.output_external(command, env=env, stderr=subprocess.STDOUT, timeout=300), False
+        except subprocess.CalledProcessError as error:
+            output = error.output if isinstance(error.output, str) else str(error.output or '')
+            conflict = 'exception specification is incompatible' in output
+        except (OSError, subprocess.SubprocessError) as error:
+            output, conflict = str(error), False
+        save(self.run_dir / 'sage-host-headers.json', {'conflict': conflict, 'compiler': env.get('CC', 'g++'), 'glibc': list(platform.libc_ver()),
+                                                      'output': output[-4000:]})
+        return conflict
+
     def host_compiler(self, cuda):
         """The compiler pair Sage is built with: the system's, a versioned one beside it, or FreeVideo's own.
 
@@ -1943,7 +1978,7 @@ def host_compiler(self, cuda):
         else:
             choice = host_compiler_choice(below, self.env['PATH'], self.env) if below else {}
         if choice is None:
-            return {'env': None, 'identity': 'conda-forge gcc ' + spec['version'] + ' static-libstdc++'}
+            return {'env': None, 'identity': pinned_compiler_identity(spec)}
         cxx = choice.get('CXX', 'g++')
         return {'env': choice, 'identity': subprocess_output.output_external([cxx, '--version']).splitlines()[0]}
 

From 9f34c0e63ba0e0cecfb5c828628cc6646fd9eaff Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 17:03:33 +0000
Subject: [PATCH 03/26] Mac: input-video encoding checks every tile for
 non-finite values and recomputes a bad tile...

Mac: input-video encoding checks every tile for non-finite values and recomputes a bad tile instead of failing after the last one

A bad tile is recomputed by repeating it, then with the original operators
(only when lean operators were in use), then on the CPU. A failure inside the
CPU level restores weights, forwards and hooks. CPU stages are not counted as
uploads, rescue start and end are logged, and the encoder error counts tiles
since the encoder was prepared.
---
 freevideo_engine/backends/mps_vae_encode.py | 104 +++++++++++++++++++-
 1 file changed, 100 insertions(+), 4 deletions(-)

diff --git a/freevideo_engine/backends/mps_vae_encode.py b/freevideo_engine/backends/mps_vae_encode.py
index fc747ce1..57431b06 100644
--- a/freevideo_engine/backends/mps_vae_encode.py
+++ b/freevideo_engine/backends/mps_vae_encode.py
@@ -1,4 +1,6 @@
 """Bound the pending Metal work and the live tensors of the original FP32 input-video encoder."""
+import json
+import time
 from contextlib import contextmanager
 
 
@@ -175,12 +177,13 @@ def forward(hidden_states):
     return forward
 
 
-def _residency(model, device, torch):
+def _residency(model, target, torch):
     """Hooks that hold each encoder stage's weights on `device` only while it runs.
 
     The weights are the same FP32 values read from the checkpoint; only the
     stage being computed is resident on the device, so the large late-stage
     weights are not alive while the early stages hold the largest activations.
+    `target` holds the device the stages upload to and whether a CPU rescue runs.
     Returns (hooks, host copies still on the device, uploaded byte counter).
     """
     encoder = model.encoder
@@ -194,8 +197,9 @@ def upload(unit, inputs):
             # A failed run leaves its stage here with the device copy in place;
             # the host copy kept from the first upload stays the source.
             host.setdefault(parameter, parameter.data)
-            parameter.data = host[parameter].to(device)
-            uploaded[0] += parameter.numel() * parameter.element_size()
+            parameter.data = host[parameter].to(target['device'])
+            if not target['rescue']:
+                uploaded[0] += parameter.numel() * parameter.element_size()
     def release(unit, inputs, output):
         for parameter in unit.parameters():
             parameter.data = host.pop(parameter)
@@ -205,6 +209,92 @@ def release(unit, inputs, output):
     return handles, host, uploaded
 
 
+CPU_TILE_LIMIT = 6
+
+
+def _finite(tensor):
+    return bool(tensor.isfinite().all())
+
+
+def _guarded_tiles(encoder, patched, target, device, staged, stats, torch):
+    """Check every tile the encoder returns and recompute a non-finite one.
+
+    A reference clip takes many minutes to encode and the pinned H3 pipeline
+    only notices a non-finite latent after the last tile. Each tile output is
+    checked here instead. A tile with non-finite values is recomputed from the
+    same input: once more on the device (a transient fault), then with the
+    original operators and the same weights, then in FP32 on the CPU for a
+    bounded number of tiles. The first level that succeeds stays in use for the
+    following tiles, except the CPU, which is only ever a per-tile rescue. A
+    tile that no level makes finite stops the encode at once with a clear error.
+    Tile numbers and the CPU limit count over every reference encoded in the
+    same `bounded_encoder` context. Only the encoder's own output is checked;
+    the layers after it (quant_conv, sampling, stitching) are not.
+    """
+    inner = encoder.forward
+    levels = ['device'] + (['plain'] if stats.get('lean_resnet_blocks') else []) + (['cpu'] if staged else [])
+    stats.update(nonfinite_tiles=0, nonfinite_recoveries={})
+    state = {'start': 0, 'tile': 0}
+    def sweep():
+        torch.mps.synchronize()
+        torch.mps.empty_cache()
+    def run(level, hidden_states):
+        if level == 'device':
+            return inner(hidden_states)
+        saved = {m: m.__dict__.pop('forward') for m in patched if 'forward' in m.__dict__}
+        try:
+            if level == 'plain':
+                return encoder(hidden_states)
+            target.update(device='cpu', rescue=True)
+            try:
+                return encoder(hidden_states.to('cpu')).to(device)
+            finally:
+                target.update(device=device, rescue=False)
+        finally:
+            encoder.__dict__.pop('forward', None)
+            for module, forward in saved.items():
+                module.__dict__['forward'] = forward
+    def forward(hidden_states):
+        state['tile'] += 1
+        output = inner(hidden_states) if state['start'] == 0 else run(levels[state['start']], hidden_states)
+        if _finite(output):
+            return output
+        del output
+        stats['nonfinite_tiles'] += 1
+        first = stats.setdefault('nonfinite_first_tile', dict(index=state['tile'], shape=list(hidden_states.shape),
+                                                              level=levels[state['start']]))
+        if first['index'] == state['tile']:
+            print(json.dumps(dict(event='encoder_nonfinite_tile', **first)), flush=True)
+        attempts = [(0, 'device-retry')] if state['start'] == 0 else []
+        attempts += [(index, level) for index, level in enumerate(levels) if index > state['start']]
+        tried = []
+        for index, level in attempts:
+            if level == 'cpu' and stats.get('cpu_tiles', 0) >= CPU_TILE_LIMIT:
+                break
+            tried.append(level)
+            sweep()
+            started = time.monotonic()
+            if level == 'cpu':
+                stats['cpu_tiles'] = stats.get('cpu_tiles', 0) + 1
+                print(json.dumps(dict(event='encoder_cpu_rescue', phase='start', tile=state['tile'],
+                                      rescued=stats['cpu_tiles'])), flush=True)
+            output = run(levels[index], hidden_states)
+            if level == 'cpu':
+                print(json.dumps(dict(event='encoder_cpu_rescue', phase='end', tile=state['tile'],
+                                      seconds=round(time.monotonic() - started, 1))), flush=True)
+            if _finite(output):
+                stats['nonfinite_recoveries'][level] = stats['nonfinite_recoveries'].get(level, 0) + 1
+                if level == 'plain':
+                    state['start'] = 1
+                return output
+            del output
+        raise RuntimeError('The reference video encoder returned non-finite values for tile %d since the reference '
+                           'encoder was prepared (%s) at every level tried (%s); the encode was stopped instead of finishing '
+                           'the remaining tiles.'
+                           % (state['tile'], 'x'.join(str(n) for n in hidden_states.shape), ', '.join(tried) or 'none'))
+    return forward
+
+
 @contextmanager
 def bounded_encoder(model, device=None):
     """Finish each convolution before submitting the next encoder operation.
@@ -227,6 +317,7 @@ def bounded_encoder(model, device=None):
     if not modules:
         raise ValueError('Expected the H3 input encoder convolution modules')
     handles, patched, host, staged, uploaded = [], [], {}, None, [0]
+    target = dict(device=device, rescue=False)
     stats = dict(policy='Complete original FP32 convolutions and release unused MPS allocations',
                  convolution_completions=0, convolution_modules=len(modules), lean_resnet_blocks=0,
                  staged_weight_bytes=0)
@@ -253,13 +344,18 @@ def complete(module, inputs, output):
             patched.append(model.encoder)
             stats['lean_resnet_blocks'] = sum(len(b.resnets) for b in model.encoder.down_blocks)
             if device is not None:
-                staged = _residency(model, device, torch)
+                staged = _residency(model, target, torch)
                 if staged is not None:
                     hooks, host, uploaded = staged
                     handles.extend(hooks)
         if device is not None and staged is None:
             # Not the pinned structure: whole model on the device, fences only.
             model.to(device)
+        encoder = getattr(model, 'encoder', None)
+        if device is not None and isinstance(encoder, torch.nn.Module):
+            if encoder not in patched:
+                patched.append(encoder)
+            encoder.forward = _guarded_tiles(encoder, patched, target, device, staged is not None, stats, torch)
         yield stats
     finally:
         if staged is not None:

From f8fd10c1d7b85cfc047740f2f58f9e30f85e9583 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 17:03:33 +0000
Subject: [PATCH 04/26] Mac: a first pass stopped by Metal or memory continues
 after its last completed step

A failed state write of any kind no longer stops the pass: torch.save reports
a failed write as RuntimeError, which the saver did not catch, so a full disk
could fail a first pass mid-sampling. Any error now marks saving as failed,
removes the partial file and lets the pass finish.
---
 freevideo_engine/geometry.py      |   7 +-
 freevideo_engine/macos_runtime.py |  31 +++++--
 freevideo_engine/macos_stages.py  |  23 ++++-
 freevideo_engine/step_grid.py     |  31 ++++++-
 freevideo_engine/step_resume.py   | 142 ++++++++++++++++++++++++++++++
 5 files changed, 220 insertions(+), 14 deletions(-)
 create mode 100644 freevideo_engine/step_resume.py

diff --git a/freevideo_engine/geometry.py b/freevideo_engine/geometry.py
index a1014d64..e51d49fe 100644
--- a/freevideo_engine/geometry.py
+++ b/freevideo_engine/geometry.py
@@ -24,7 +24,7 @@ def geometry(width=1344, height=768, frames=None, seconds=None):
                 alignment='Pinned H3 VAE: round up to 17*n+5 frames; no resampling or hidden resolution reduction.')
 
 
-def sampler_for_canvas(sampler, width, height):
+def sampler_for_canvas(sampler, width, height, scheduler=None):
     """Bind canvas constants in an isolated globals dict, preserving upstream code.
 
     Engine.sample supplies no_grad. Never edit the upstream file or mutate its
@@ -32,7 +32,10 @@ def sampler_for_canvas(sampler, width, height):
     The upstream sampler builds its schedulers by name; it gets the engine's,
     whose step grid is the one the modulation tables were made with.
     """
-    from .step_grid import scheduler
+    from .step_grid import scheduler as engine_scheduler
+    # A caller may supply a factory that adds a start step or an observer to the
+    # same engine scheduler; the default is that scheduler itself.
+    scheduler = scheduler or engine_scheduler
     original = inspect.unwrap(sampler)
     bound = types.FunctionType(original.__code__,
         dict(original.__globals__, LATENT_H=height // 16, LATENT_W=width // 16,
diff --git a/freevideo_engine/macos_runtime.py b/freevideo_engine/macos_runtime.py
index 694e5a01..19a41851 100644
--- a/freevideo_engine/macos_runtime.py
+++ b/freevideo_engine/macos_runtime.py
@@ -495,7 +495,7 @@ def sample(self, *args, **kwargs):
             return result
 
     def _sample(self, conditioning, seed, *, width, height, frames, progress_offset=0, progress_total=None,
-               initial_latents=None, refine_steps=None, refine_schedule=None, continuation=None):
+               initial_latents=None, refine_steps=None, refine_schedule=None, continuation=None, step_state=None):
         import torch
         from .geometry import geometry, sampler_for_canvas
         from .system import system_memory
@@ -531,9 +531,19 @@ def _sample(self, conditioning, seed, *, width, height, frames, progress_offset=
             from .reference_sampler import generate_latents
         active_steps = refine_steps if refining else self.steps
         canvas = geometry(width, height, frames=frames)
-        sampler = sampler_for_canvas(generate_latents, width, height)
-        progress = MacSamplingProgress(active_steps, len(self.model.transformer_blocks),
-                                    offset=progress_offset, total=progress_total)
+        # Only the plain first pass without a step cache saves its steps; a retry
+        # of it continues after the last saved one.
+        resumable = (step_state is not None and not refining and self.task == 't2va'
+                     and continuation is None and not self.step_cache)
+        resumed = step_state.load() if resumable else None
+        start = step_state.start if resumed else 0
+        sampler = sampler_for_canvas(generate_latents, width, height,
+                                     scheduler=step_state.scheduler if resumable else None)
+        progress = MacSamplingProgress(active_steps - start, len(self.model.transformer_blocks),
+                                    offset=progress_offset + start,
+                                    total=progress_total if progress_total is not None else active_steps + progress_offset)
+        if start:
+            print(json.dumps(dict(event='step_resume', completed_steps=start, total=active_steps)), flush=True)
         prefix = None
         class StepTimes(list):
             def append(owner, duration):
@@ -541,6 +551,8 @@ def append(owner, duration):
                     prefix.restore_video()
                 super().append(duration)
                 progress.complete(duration)
+                if resumable:
+                    step_state.completed(duration)
         durations = StepTimes()
         previous_calls = dict(self.attention.backend_calls)
         previous_kernel_calls = {name: dict(counts) for name, counts in
@@ -568,7 +580,7 @@ def host_guard(module, inputs):
                                                      + 2 * continuation['audio'].shape[2])
                 self._plan_compute(canvas, prompt.shape[0])
                 previous_block_calls = self._block_metrics()
-                self.cursor.reset(self.steps - refine_steps if refining and refine_schedule is None else 0)
+                self.cursor.reset(self.steps - refine_steps if refining and refine_schedule is None else start)
                 progress.start()
                 resident = getattr(self, 'resident_bytes', 0)
                 retention = (dict(resident_bytes=resident, working_reserve_bytes=self.reserve_bytes)
@@ -589,7 +601,7 @@ def host_guard(module, inputs):
                         audio_offset=canvas.get('reference_audio_tokens', 0)) as prefix, \
                         progress.layers(self.model.transformer_blocks), \
                         frame_preview.observing(latent_frames=canvas['latent_frames'], frame_h=height // 32,
-                                                frame_w=width // 32, step_offset=progress_offset,
+                                                frame_w=width // 32, step_offset=progress_offset + start,
                                                 total=progress_total if progress_total is not None else active_steps):
                     self.residency = residency
                     from .step_cache import begin_pass, end_pass
@@ -597,12 +609,16 @@ def host_guard(module, inputs):
                     if not refining and self.step_cache:
                         begin_pass(self.model, active_steps, self.step_cache)
                     try:
+                        if resumable:
+                            step_state.attach(self.model, self.backend.device)
                         video, audio = sampler(self.model, prompt, tags, canvas['frames'], self.steps,
                                               seed, self.backend.device, step_seconds=durations,
                                               **(dict(conditions=conditions) if conditions else {}),
                                               **(dict(initial_latents=initial_latents, refine_steps=refine_steps, refine_schedule=refine_schedule)
                                                  if refining else {}))
                     finally:
+                        if resumable:
+                            step_state.detach()
                         step_cache = end_pass(self.model)
                     if prefix is not None:
                         video, audio = prefix.finish(video, audio)
@@ -628,7 +644,8 @@ def host_guard(module, inputs):
                                               max_bytes=max(self.allocator_limits)),
                         attention_calls={name: value - previous_calls[name]
                                          for name, value in self.attention.backend_calls.items()},
-                        step_seconds=list(durations), step_cache=step_cache,
+                        step_seconds=list(step_state.previous_seconds if resumable else durations), step_cache=step_cache,
+                        **(dict(resumed_from_step=start) if start else {}),
                         block_seconds=progress.block_seconds, block_seconds_scope=BLOCK_SECONDS_SCOPE,
                         conditions=progress.conditions,
                         load_seconds=self.load_seconds, residency=self._residency_metrics(residency, previous_residency),
diff --git a/freevideo_engine/macos_stages.py b/freevideo_engine/macos_stages.py
index b5df0c92..43b1328d 100644
--- a/freevideo_engine/macos_stages.py
+++ b/freevideo_engine/macos_stages.py
@@ -12,7 +12,7 @@
 import time
 import traceback
 
-from . import processes
+from . import processes, step_resume
 from .locking import LOCK_ENV, runtime_lock
 from .monitoring import save
 
@@ -182,6 +182,9 @@ def interrupted(signum, frame):
                     continue
                 result['phase'] = stage
                 save(path, result)
+                if stage == 'first-pass':
+                    # Steps saved by an earlier request's pass must never be resumed.
+                    step_resume.discard(artifacts)
                 request = artifacts / (stage + '-request.json')
                 receipt = artifacts / (stage + '-result.json')
                 while True:
@@ -198,6 +201,13 @@ def interrupted(signum, frame):
                             pass_fds=(descriptor,), check=True)
                     except subprocess.CalledProcessError:
                         failed = read_receipt(receipt)
+                        if failed.get('error_type') == 'ResumeRejected' and (artifacts / 'first-pass-step.pt').is_file():
+                            # The saved step did not reach the sampler. Start the pass
+                            # over without spending the retry.
+                            step_resume.discard(artifacts)
+                            result.setdefault('resume_rejections', []).append(failed.get('error_message'))
+                            receipt.unlink(missing_ok=True)
+                            continue
                         if not memory_exhausted(stage, failed):
                             raise
                         metal = METAL_FAILURE in str(failed.get('error_message', ''))
@@ -246,6 +256,8 @@ def interrupted(signum, frame):
                     if stage in ('first-pass', 'refinement'):
                         # A later pass's failure is not a consecutive failed retry.
                         metal_retry = False
+                    if stage == 'first-pass':
+                        step_resume.discard(artifacts)
                     break
                 if stage == 'first-pass' and retained_joined:
                     continue
@@ -440,6 +452,14 @@ def capture_first(video):
                 # A memory retry keeps each pass in its own process.
                 admission = (joined_admission(engine, value) if not refining and not retry
                              and value.get('preview') is not True else dict(selected=False))
+                # A first pass saves each step so that a retry can continue after the last one.
+                step_state = None
+                if not refining and not admission['selected']:
+                    try:
+                        step_state = step_resume.StepState(step_resume.step_path(artifacts),
+                            first_pass_identity(value), sampling['base_steps'])
+                    except (OSError, KeyError, ValueError):
+                        step_state = None
                 result['sampling_admission'] = admission
                 if admission['selected']:
                     result.update(joined_sampling=True, sampling_passes=[], latent_save_seconds=0.)
@@ -471,6 +491,7 @@ def first_saved(video, audio, metrics):
                 else:
                     video, audio, measured = engine.sample(value['conditioning'],
                         value['seed'] + (sampling['restart_seed_offset'] if refining else 0),
+                        **(dict(step_state=step_state) if step_state is not None else {}),
                         **sampling['second' if refining else 'first'],
                         **(dict(continuation=chain.load(continuation, 'final' if refining else 'first'))
                            if continuation is not None else {}),
diff --git a/freevideo_engine/step_grid.py b/freevideo_engine/step_grid.py
index a7babfcc..ab2f9195 100644
--- a/freevideo_engine/step_grid.py
+++ b/freevideo_engine/step_grid.py
@@ -37,23 +37,46 @@ def _scheduler_class():
     from diffusers import MiniMaxH3Scheduler
 
     class Scheduler(MiniMaxH3Scheduler):
+        # A request resuming after step `start` iterates only the steps still to
+        # run, on the unchanged sigma grid; `observer` sees every update.
+        start = 0
+        observer = None
+
         def set_timesteps(self, num_inference_steps=None, device=None, sigmas=None):
             if sigmas is None and type(num_inference_steps) is int and num_inference_steps >= 1:
                 base = uniform(num_inference_steps)
                 # The scheduler's own shift, applied to a grid it did not build.
                 sigmas = self._shift * base / (1 + (self._shift - 1) * base)
             super().set_timesteps(num_inference_steps, device=device, sigmas=sigmas)
+            if self.start:
+                if not 0 < self.start < len(self.timesteps):
+                    raise ValueError('A resumed schedule must start inside its steps')
+                # The step index then comes from this begin index; the sigmas keep
+                # their original positions.
+                self.timesteps = self.timesteps[self.start:]
+                self.set_begin_index(self.start)
 
         def step(self, model_output, timestep, sample, return_dict=True):
             # Read-only: the frame preview looks at the prediction, then the
             # upstream update runs exactly as before.
             from .frame_preview import observe
             observe(model_output, timestep, sample)
-            return super().step(model_output, timestep, sample, return_dict=return_dict)
+            result = super().step(model_output, timestep, sample, return_dict=return_dict)
+            if self.observer is not None:
+                self.observer(self, sample, result[0] if isinstance(result, tuple) else result.prev_sample)
+            return result
 
     return Scheduler
 
 
-def scheduler(shift=12.):
-    """A MiniMaxH3Scheduler whose step grid is `uniform`; explicit sigmas pass through."""
-    return _scheduler_class()(shift=shift)
+def scheduler(shift=12., *, start=0, observer=None):
+    """A MiniMaxH3Scheduler whose step grid is `uniform`; explicit sigmas pass through.
+
+    `start` resumes a schedule after that many completed steps; `observer(scheduler,
+    sample, updated)` is called after each update."""
+    made = _scheduler_class()(shift=shift)
+    if start:
+        made.start = start
+    if observer is not None:
+        made.observer = observer
+    return made
diff --git a/freevideo_engine/step_resume.py b/freevideo_engine/step_resume.py
new file mode 100644
index 00000000..0d1680c7
--- /dev/null
+++ b/freevideo_engine/step_resume.py
@@ -0,0 +1,142 @@
+"""Resume a native first pass from its last completed sampling step.
+
+A sampling pass that Metal or the unified-memory allocator stops is attempted
+again in a fresh process. Without a saved state that attempt repeats every
+completed step, which on a slow Mac is most of the lost time. This module saves
+the generated video and audio rows after every step of the plain first pass and
+lets the retry continue from them.
+
+The vendored sampler is not changed. It is bound to the engine's scheduler, so
+a resumed scheduler iterates only the remaining steps on the original sigma grid
+(the step index comes from the begin index), the scheduler's observer keeps the
+rows each update returns, and a one-shot forward hook writes the saved rows into
+the sampler's input tensors before the first resumed forward. That first update
+then verifies that the saved rows are what the sampler stepped from; if the
+sampler no longer shares those tensors the pass stops with `ResumeRejected` and
+the controller starts the pass over.
+
+Only the plain text-to-video pass without a step cache or continuation is
+resumable. Every other pass behaves as before.
+"""
+import os
+from pathlib import Path
+
+VERSION = 1
+VIDEO_SHIFT, AUDIO_SHIFT = 12., 3.        # the vendored sampler's defaults
+
+
+class ResumeRejected(RuntimeError):
+    """The saved step could not be applied; the pass must start from step one."""
+
+
+class StepState:
+    """Saves the rows after each step, and applies a matching saved step once."""
+
+    def __init__(self, path, identity, steps):
+        self.path, self.identity, self.steps = Path(path), identity, steps
+        self.saved = self.resume = None
+        self.start = 0
+        self.previous_seconds = []
+        self.finished = 0
+        self._rows = {}
+        self._hook = None
+        self._verified = set()
+        self.failed = None
+
+    def load(self):
+        """The saved state when it belongs to this pass, else None."""
+        import torch
+        try:
+            saved = torch.load(self.path, map_location='cpu', weights_only=True)
+        except Exception:
+            # A missing, truncated or foreign file is just no saved step.
+            return None
+        if not isinstance(saved, dict):
+            return None
+        done = saved.get('completed')
+        if (saved.get('version') != VERSION or saved.get('identity') != self.identity
+                or saved.get('steps') != self.steps or type(done) is not int
+                or not 0 < done < self.steps or len(saved.get('step_seconds', ())) != done
+                or not all(isinstance(saved.get(key), torch.Tensor) and bool(saved[key].isfinite().all())
+                           for key in ('video', 'audio'))):
+            return None
+        self.resume, self.start = saved, done
+        self.previous_seconds = [float(seconds) for seconds in saved['step_seconds']]
+        self.finished = done
+        return saved
+
+    def scheduler(self, shift=12., **options):
+        """The engine scheduler for the sampler: resumed, and observed."""
+        from .step_grid import scheduler
+        return scheduler(shift, start=self.start, observer=self._observe, **options)
+
+    def _observe(self, scheduler, sample, updated):
+        kind = {VIDEO_SHIFT: 'video', AUDIO_SHIFT: 'audio'}.get(scheduler.shift)
+        if kind is None:
+            self.failed = 'unknown schedule'
+            return
+        if self.resume is not None and kind not in self._verified:
+            import torch
+            # `sample` is the sampler's own tensor, overwritten right after this
+            # update; compare it now, before the sampler stores the result.
+            if not torch.equal(sample.detach().cpu(), self.resume[kind]):
+                raise ResumeRejected('The saved ' + kind + ' rows were not the sampler input')
+            self._verified.add(kind)
+        self._rows[kind] = updated
+
+    def attach(self, model, device):
+        """Write the saved rows into the first forward's inputs; no-op without a saved step."""
+        if self.resume is None:
+            return
+        def inject(module, args, kwargs):
+            self._hook.remove()
+            for name, key in (('hidden_states', 'video'), ('audio_hidden_states', 'audio')):
+                target, rows = kwargs[name][0], self.resume[key]
+                if tuple(target.shape) != tuple(rows.shape):
+                    raise ResumeRejected('The saved rows do not fit the sampler input')
+                target.copy_(rows.to(device=target.device, dtype=target.dtype))
+        self._hook = model.register_forward_pre_hook(inject, with_kwargs=True)
+
+    def detach(self):
+        if self._hook is not None:
+            self._hook.remove()
+            self._hook = None
+
+    def completed(self, seconds):
+        """A step finished: keep its rows so a retry can continue after it."""
+        import torch
+        self.finished += 1
+        self.previous_seconds.append(float(seconds))
+        if self.failed or self.finished >= self.steps or set(self._rows) != {'video', 'audio'}:
+            return
+        temporary = self.path.with_name(self.path.name + '.partial')
+        try:
+            torch.save(dict(version=VERSION, identity=self.identity, steps=self.steps, completed=self.finished,
+                            step_seconds=list(self.previous_seconds),
+                            video=self._rows['video'].detach().cpu(), audio=self._rows['audio'].detach().cpu()),
+                       temporary)
+            os.replace(temporary, self.path)
+        except Exception as error:
+            # Saving is an optimization: without it a retry starts over. A failed
+            # write is an OSError from the rename but a RuntimeError from torch.save.
+            self.failed = str(error) or type(error).__name__
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass
+        self._rows = {}
+
+    def clear(self):
+        for path in (self.path, self.path.with_name(self.path.name + '.partial')):
+            path.unlink(missing_ok=True)
+
+
+def step_path(artifacts):
+    return Path(artifacts) / 'first-pass-step.pt'
+
+
+def discard(artifacts):
+    """Remove a pass's saved step; a new pass must never meet an older one's."""
+    path = step_path(artifacts)
+    for stale in (path, path.with_name(path.name + '.partial')):
+        stale.unlink(missing_ok=True)

From e1c3b64f20b9e960518aa187f4960368c11be61d Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 18:01:19 +0000
Subject: [PATCH 05/26] Add optional dialogue, music and ambience sound
 separation with sub-tracks, a toolbar button and...

Add optional dialogue, music and ambience sound separation with sub-tracks, a toolbar button and track export
---
 THIRD_PARTY_NOTICES.md                        |   1 +
 freevideo_engine/agent/errors.py              |   6 +
 freevideo_engine/agent/guide.py               |   4 +
 freevideo_engine/agent/jobs.py                |   5 +-
 freevideo_engine/agent/projects.py            |  65 ++++
 freevideo_engine/agent/routes.py              |  24 +-
 freevideo_engine/agent/schema.py              |  36 +-
 freevideo_engine/agent/spec.py                |   3 +
 freevideo_engine/agent/stems.py               |  85 +++++
 freevideo_engine/comfy_editor.py              |   8 +-
 freevideo_engine/comfy_nodes.py               |   5 +
 freevideo_engine/comfy_progress.py            |  13 +
 freevideo_engine/editor_audio.py              |  17 +
 freevideo_engine/editor_export.py             |   4 +-
 freevideo_engine/editor_text.py               |   2 +-
 freevideo_engine/image_gen/image_models.json  |  21 ++
 freevideo_engine/image_gen/image_pack.py      |  13 +-
 .../licenses/Bandit-Apache-2.0.txt            | 207 +++++++++++
 .../licenses/Bandit-CC-BY-NC-4.0.txt          |  10 +
 freevideo_engine/stems/__init__.py            |   0
 freevideo_engine/stems/bandit/__init__.py     |   2 +
 freevideo_engine/stems/bandit/bandsplit.py    | 141 +++++++
 freevideo_engine/stems/bandit/base.py         |  20 +
 freevideo_engine/stems/bandit/core.py         | 236 ++++++++++++
 freevideo_engine/stems/bandit/maskestim.py    | 348 ++++++++++++++++++
 freevideo_engine/stems/bandit/spectral.py     |  60 +++
 freevideo_engine/stems/bandit/tfmodel.py      | 177 +++++++++
 freevideo_engine/stems/bandit/utils.py        | 260 +++++++++++++
 freevideo_engine/stems/bandit/wrapper.py      | 190 ++++++++++
 freevideo_engine/stems/separate.py            | 200 ++++++++++
 freevideo_engine/stems/service.py             | 176 +++++++++
 freevideo_engine/stems/worker.py              |  40 ++
 web/editor.css                                |   1 +
 web/editor.js                                 |  10 +-
 web/editor_audio_model.js                     |  13 +
 web/editor_menu.js                            |   5 +-
 web/editor_model.js                           |  37 +-
 web/editor_player.js                          |   3 +-
 web/editor_room.js                            |   2 +-
 web/editor_stems.js                           | 168 +++++++++
 web/editor_text_model.js                      |   2 +-
 web/editor_tracks.css                         |  10 +-
 web/editor_tracks.js                          |  17 +-
 web/health.js                                 |   2 +-
 44 files changed, 2609 insertions(+), 40 deletions(-)
 create mode 100644 freevideo_engine/agent/stems.py
 create mode 100644 freevideo_engine/licenses/Bandit-Apache-2.0.txt
 create mode 100644 freevideo_engine/licenses/Bandit-CC-BY-NC-4.0.txt
 create mode 100644 freevideo_engine/stems/__init__.py
 create mode 100644 freevideo_engine/stems/bandit/__init__.py
 create mode 100644 freevideo_engine/stems/bandit/bandsplit.py
 create mode 100644 freevideo_engine/stems/bandit/base.py
 create mode 100644 freevideo_engine/stems/bandit/core.py
 create mode 100644 freevideo_engine/stems/bandit/maskestim.py
 create mode 100644 freevideo_engine/stems/bandit/spectral.py
 create mode 100644 freevideo_engine/stems/bandit/tfmodel.py
 create mode 100644 freevideo_engine/stems/bandit/utils.py
 create mode 100644 freevideo_engine/stems/bandit/wrapper.py
 create mode 100644 freevideo_engine/stems/separate.py
 create mode 100644 freevideo_engine/stems/service.py
 create mode 100644 freevideo_engine/stems/worker.py
 create mode 100644 web/editor_stems.js

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 49829717..64906f63 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -21,6 +21,7 @@ FreeVideo code uses [Apache-2.0](LICENSE). Its dependencies and models retain th
 | [Eigen](https://gitlab.com/libeigen/eigen) 5.0.1, compiled into sherpa-onnx and ONNX Runtime; source: https://gitlab.com/libeigen/eigen/-/tree/5.0.1 | MPL-2.0 |
 | [Silero VAD](https://github.com/snakers4/silero-vad) v5.0 voice-activity model, © 2020-present Silero Team (optional download with subtitles, license file downloaded with the model; the onnx-community export is downloaded with the music model) | [MIT](freevideo_engine/licenses/Silero-VAD-MIT.txt) |
 | [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) XL turbo music model, © 2026 ACEStep (optional download for music; inference subset adapted in `freevideo_engine/music/acestep_model.py`) | [MIT](freevideo_engine/licenses/ACE-Step-MIT.txt) |
+| [Bandit Plus](https://zenodo.org/records/10160698) cocktail-party separation model, weights by Watcharasupat et al. (optional download for sound separation, attribution required, non-commercial); code from [Bandit](https://github.com/kwatcharasupat/source-separation), © the Bandit authors, reduced to an inference subset in `freevideo_engine/stems/bandit/` (modified) | [CC BY-NC 4.0](freevideo_engine/licenses/Bandit-CC-BY-NC-4.0.txt) (weights), [Apache-2.0](freevideo_engine/licenses/Bandit-Apache-2.0.txt) (code) |
 | [vector-quantize-pytorch](https://github.com/lucidrains/vector-quantize-pytorch), © 2020 Phil Wang (residual FSQ decoding adapted in `freevideo_engine/music/acestep_model.py`) | [MIT](freevideo_engine/licenses/Vector-Quantize-PyTorch-MIT.txt) |
 | [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B), © Alibaba Cloud (text encoder of the music model, downloaded with it) | [Apache-2.0](freevideo_engine/licenses/Qwen3-Embedding-Apache-2.0.txt) |
 | [NVIDIA NeMo stt_en_conformer_ctc_small](https://huggingface.co/nvidia/stt_en_conformer_ctc_small), © NVIDIA, exported to ONNX and quantized to int8 by the sherpa-onnx project, changed from the original; not endorsed by NVIDIA (optional download for English subtitles; [notice](freevideo_engine/licenses/NeMo-stt_en_conformer_ctc_small-NOTICE.txt)) | [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) |
diff --git a/freevideo_engine/agent/errors.py b/freevideo_engine/agent/errors.py
index 6c03fe6b..8f11a97f 100644
--- a/freevideo_engine/agent/errors.py
+++ b/freevideo_engine/agent/errors.py
@@ -121,6 +121,10 @@
                               'submit the music job again with a new ref; if it fails again, write the score yourself.'),
     'music_failed': (409, True, 'Composing the music did not finish.',
                      'Read the project, then submit the music job again with a new ref; if it fails again, write the score yourself.'),
+    'stems_download_failed': (409, True, 'The sound separation model could not be downloaded.',
+                              'Tell the user the model needs a network connection, then submit the job again with a new ref.'),
+    'stems_failed': (409, True, 'Splitting the sound did not finish.',
+                     'Read the project, then submit the job again with a new ref; if it fails again, leave the sound as it is.'),
     'clip_source_unusable': (409, False, 'A clip\'s source is missing, or cannot be read as far as the clip uses it.',
                              'Read the project and check each clip\'s source: it must exist and play, and in + frames must stay '
                              'within its real length. Correct the project, then export the new revision.'),
@@ -235,6 +239,8 @@ def recovery(code, *, kind=None, stage='request', resumable=True):
         return 'Tell the user to free disk space, then submit the picture again with a new ref.'
     if kind == 'music' and code == 'out_of_memory':
         return 'Close other GPU applications, then submit the music job again with a new ref.'
+    if kind == 'stems' and code == 'out_of_memory':
+        return 'Close other GPU applications, then submit the job again with a new ref.'
     if kind == 'image' and code == 'no_memory':
         return 'Lower the picture dimensions or use fewer reference pictures, then submit with a new ref.'
     if kind in RECOVERY and stage == 'terminal':
diff --git a/freevideo_engine/agent/guide.py b/freevideo_engine/agent/guide.py
index f0095b93..81726d2d 100644
--- a/freevideo_engine/agent/guide.py
+++ b/freevideo_engine/agent/guide.py
@@ -144,6 +144,7 @@
         'On 409 project_changed, recompute edits from error.project and its current_revision, then send a new request. On clip_busy wait for generation to finish.',
         'POST /projects/{id}/generate reserves pending parts for clip_ids or a start/frames range and fills them as the returned job finishes. POST /projects/{id}/export renders the revision you read; wait for its job.',
         'Music: POST /projects/{id}/music with the revision you read and a caption; wait for the job, then read the project: result.clip_ids are the new clips on a2. Run it after the cut is joined; a second run needs the earlier score removed from a2.',
+        'Split sound: POST /projects/{id}/stems with the revision you read and the clip_id of a sound clip; wait for the job. The clip\'s sound is split into dialogue, music and ambience on tracks a4, a5 and a6 over the clip\'s range, and the clip itself goes silent. result.parts lists each track with its name, clip_id, start, end and frames. Offered only where features lists projects.stems; a clip is split once, and deleting the three parts gives its sound back. To save the three tracks and the original mix as four wav files, POST /projects/{id}/stems/export with the revision and the split clip\'s clip_id; the answer lists folder and files at once.',
         'Subtitles: POST /projects/{id}/listen with mode transcribe (writes down what is said) or align (times the lines you give) and the revision you read; wait for the job and read result.lines, each with start and end frames. Then add them with a subtitles operation of cues {start, frames, text}; replace true swaps the whole track. With no speech model the job fails with no_speech_model: write the lines yourself.',
         'The user sees one line under each picture clip: its note, or else the first line of its description. A description is generation text, often long and in English, so after you add, generate or change a clip, write a note (operation note) in the user\'s language saying what is in the picture: the subject first, then the setting, for example "Train through morning mist" (in Chinese "小火车穿过晨雾"). A short clip shows only the first few characters, about four in Chinese, and those must already make sense on their own. Do not write where the clip sits (opening, middle, ending, part 2): the order of the clips shows that. Do not write how far along it is: the clip already shows its progress. Keep it true when you change the clip again.',
         'Reuse ref or Idempotency-Key only for the identical request. Source video/audio/thumbnail URLs require the same Agent token.',
@@ -377,6 +378,9 @@
         '没有安装语音模型时返回 no_speech_model，改为自己写字幕行',
     ('POST', '/projects/{id}/music'): '为剪辑时间线作一段与其等长的配乐，放在第二条声音轨道的开头，音量低于视频声音并带淡入淡出。'
         '剪辑拼好后先读取 revision，并删去该轨道上原有的配乐；首次使用会下载音乐模型（约 20 GB）',
+    ('POST', '/projects/{id}/stems'): '把一个声音片段的声音分成人声、音乐和环境声，放在其下方的 a4、a5、a6 三条轨道上，原片段静音。'
+        '先读取 revision 与片段 ID，等待返回的任务完成，结果 parts 给出各轨道的名称、起止帧；仅在 features 含 projects.stems 时可用',
+    ('POST', '/projects/{id}/stems/export'): '把已拆开片段的人声、音乐、环境声和原混音保存为四个 wav 文件；先读取 revision 与被拆片段的 ID，返回立即给出文件夹和文件名',
     ('POST', '/images'): '像图片编辑页面一样打开图片；提交 source，会话会保留源图片副本和图层文档',
     ('GET', '/images/{id}'): '读取图片编辑会话的图层文档、选区和 revision；编辑前先读取 revision 和图层标识',
     ('PUT', '/images/{id}'): '替换整个图片文档；先读取会话并提交其 revision。'
diff --git a/freevideo_engine/agent/jobs.py b/freevideo_engine/agent/jobs.py
index 9cd7488e..53d5b346 100644
--- a/freevideo_engine/agent/jobs.py
+++ b/freevideo_engine/agent/jobs.py
@@ -32,7 +32,7 @@
 ACTIVE = ('waiting', 'queued', 'running', 'cancelling')
 CAST_AGAIN = 'POST /freevideo/agent/v1/cast/%s/generate to make the reference pictures again.'
 DONE = ('succeeded', 'failed', 'cancelled', 'interrupted')
-GPU_KINDS = ('vlm', 'enhance', 'image', 'music')
+GPU_KINDS = ('vlm', 'enhance', 'image', 'music', 'stems')
 IMAGE_ERRORS = errors.IMAGE_ERRORS
 IMAGE_WAIT_ERRORS = ('busy', 'busy_video')
 IMAGE_WAIT_NOTICES = {
@@ -1485,6 +1485,9 @@ def run():
             elif row['kind'] == 'music':
                 from .music import run_music
                 result = run_music(self, row)
+            elif row['kind'] == 'stems':
+                from .stems import run_stems
+                result = run_stems(self, row)
             else:
                 result = self.run_assemble(row)
             return result
diff --git a/freevideo_engine/agent/projects.py b/freevideo_engine/agent/projects.py
index dd7e2f2f..619935cb 100644
--- a/freevideo_engine/agent/projects.py
+++ b/freevideo_engine/agent/projects.py
@@ -11,6 +11,7 @@
 import hashlib
 import json
 import logging
+from pathlib import Path
 import re
 import secrets
 import threading
@@ -413,6 +414,70 @@ def music(self, identity, value, *, jobs, ref=None, client=None):
             self._remember(ref, digest, result, client)
             return result
 
+    def stems(self, identity, value, *, jobs, ref=None, client=None):
+        """Queue a sound-splitting job for one sound clip of the revision the caller read."""
+        schema.validate(schema.project_schema('stems'), value)
+        with self.listen_lock:
+            digest, replay = self._receipt('projects:stems', dict(id=identity, body=value), ref, client)
+            if replay is not None:
+                return replay
+            stored = self._load(identity)['project']
+            if stored['revision'] != value['revision']:
+                raise ProjectError('project_changed', project=stored)
+            clip = _clips(stored).get(value['clip_id'])
+            if clip is None or not clip.get('source') or clip.get('stem_of'):
+                raise _invalid('/clip_id', 'a sound clip with media that is not itself a separated part', value['clip_id'])
+            job = jobs.submit(dict(kind='stems', editor_project=identity,
+                                   **{k: v for k, v in value.items() if k != 'ref'}), client=client)[0]
+            result = dict(job=jobs.view(job), jobs=[jobs.view(job)])
+            self._remember(ref, digest, result, client)
+            return result
+
+    def stems_export(self, identity, value, *, ref=None, client=None):
+        """Copy the four wav files of a split clip into the saved sounds; the clip must be one that was split."""
+        from ..stems.separate import SeparationError, export_tracks
+        schema.validate(schema.project_schema('stems_export'), value)
+        with self.listen_lock:
+            digest, replay = self._receipt('projects:stems_export', dict(id=identity, body=value), ref, client)
+            if replay is not None:
+                return replay
+            stored = self._load(identity)['project']
+            if stored['revision'] != value['revision']:
+                raise ProjectError('project_changed', project=stored)
+            parts = [clip for clip in _clips(stored).values() if clip.get('stem_of') == value['clip_id']]
+            if not parts:
+                raise _invalid('/clip_id', 'a clip that was split into dialogue, music and ambience', value['clip_id'])
+            folder = parts[0]['source']['id'].rsplit('/', 1)[0]
+            if not folder.startswith('freevideo-stems/') or folder.count('/') != 1:
+                raise _invalid('/clip_id', 'a clip split by this version', value['clip_id'])
+            name = folder.split('/', 1)[1]
+            try:
+                files = export_tracks(Path(self.root) / folder, Path(self.root) / 'freevideo-stems-saved' / name)
+            except SeparationError as error:
+                raise JobError('stems_failed', 'The separated sound cannot be saved (%s)' % error) from error
+            result = dict(editor_project=identity, revision=stored['revision'], clip_id=value['clip_id'],
+                          folder='freevideo-stems-saved/' + name, files=files)
+            self._remember(ref, digest, result, client)
+            return result
+
+    def lay_stems(self, identity, clip_id, sources):
+        """Put the three parts on sub-tracks under the clip and silence the clip; returns the save and the new clip IDs."""
+        before, refused = {}, {}
+        def change(project):
+            before['ids'] = set(_clips(project))
+            reply = editor_runtime.runtime().call('placeStems', project, [clip_id, {
+                name: dict(kind='generated', id=source.split(':', 1)[1]) for name, source in sources.items()}],
+                module='model', serialize=True)[0]
+            if not reply['ok']:
+                refused.update(reply['error'])
+                return dict(ok=True, project=project)
+            return dict(ok=True, project=reply['value'])
+        saved = self._update(identity, change)
+        if refused:
+            code = STATE_CODES.get(refused.get('code'), 'stems_failed')
+            raise JobError(code, 'The separated sound cannot be laid under the clip (%s)' % refused.get('code'))
+        return saved, sorted(set(_clips(saved)) - before['ids'])
+
     def lay_music(self, identity, source):
         """Put a finished score on a2 from frame 0 of the project as it is now; returns the save and the new clip IDs."""
         found = comfy_editor.sources(self.root, [source])[source]
diff --git a/freevideo_engine/agent/routes.py b/freevideo_engine/agent/routes.py
index c95fcdd1..79c82b5c 100644
--- a/freevideo_engine/agent/routes.py
+++ b/freevideo_engine/agent/routes.py
@@ -172,7 +172,13 @@ def submit_batch(jobs, body, client):
     return jobs.submit_request(body, client=client)[0]
 
 
-def features(continuation, vlm):
+def stems_supported(machine):
+    """Sound separation is offered on NVIDIA machines with enough video memory, never on a Mac."""
+    from ..stems.service import supported
+    return supported(machine.get('vram_gib'), uuid=machine.get('gpu_uuid')) and machine.get('device_backend', 'cuda') == 'cuda'
+
+
+def features(continuation, vlm, stems=False):
     """What an agent can use here (ready says whether the engine can run now). A missing name is not offered."""
     from .editor_runtime import available
     rules = available()
@@ -183,7 +189,8 @@ def features(continuation, vlm):
             'queue.shared': True, 'queue.busy': True, 'chain.auto': bool(continuation),
             'enhance': bool(vlm.get('ready')), 'drama.film': True, 'images.edit': rules,
             'images.layers': rules, 'images.heal': rules, 'images.render': rules, 'projects.read': True,
-            **{'projects.' + name: rules for name in ('insert', 'split', 'move', 'trim', 'remove', 'export', 'generate', 'listen', 'music')}}
+            **{'projects.' + name: rules for name in ('insert', 'split', 'move', 'trim', 'remove', 'export', 'generate', 'listen', 'music')},
+            'projects.stems': bool(rules and stems)}
 
 
 def whitebox_support(jobs):
@@ -221,7 +228,7 @@ def capabilities(port, jobs):
     return dict(
         api_version=API_VERSION, freevideo_version=release or __version__, build=__version__, ready=ready, problem=problem,
         continuation=continuation,
-        features=features(continuation, vlm),
+        features=features(continuation, vlm, stems=stems_supported(machine)),
         whitebox=whitebox_support(jobs),
         device=dict(backend=machine.get('device_backend', 'cuda') if machine else None,
                     vram_limit_gib=machine.get('vram_gib'), ram_limit_gib=machine.get('ram_gib')),
@@ -233,6 +240,7 @@ def capabilities(port, jobs):
                'export': 'Render a saved revision of an editing project to a video',
                'listen': 'Listen to the sound of an editing project for subtitle lines and times',
                'music': 'Compose music for an editing project and lay it on its second sound track',
+               'stems': 'Split the sound of a clip into dialogue, music and ambience on sub-tracks',
                'image_edit': 'Render a saved revision of an image session to a picture'},
         limits=dict(width=[256, 4096, 32], height=[256, 4096, 32], seconds=[1.625, 60 if continuation else BLOCK_SECONDS],
                     seconds_tested=[4, 15],
@@ -507,7 +515,9 @@ async def respond(request):
                         raise JobError('page_session_required', 'Page session required')
                 header = request.headers.get('Authorization', '')
                 given = header[7:].strip() if header[:7].lower() == 'bearer ' else request.headers.get('X-FreeVideo-Agent', '')
-                if definition.get('auth', True) or given:
+                # The editor page may drive a few routes with its page session instead of the token.
+                by_page = bool(definition.get('page_ok')) and not given and valid_page_session(request)
+                if (definition.get('auth', True) and not by_page) or given:
                     try:
                         token = expected()
                     except (OSError, ValueError):
@@ -2215,7 +2225,7 @@ async def handler(request):
                 raise JobError('idempotency_conflict', 'Conflicting keys')
             args = [] if operation == 'create' else [identity]
             extra = dict(client=request.headers.get('X-FreeVideo-Client', '')[:80] or None)
-            if operation in ('generate', 'export', 'listen', 'music'):
+            if operation in ('generate', 'export', 'listen', 'music', 'stems'):
                 extra['jobs'] = jobs
             if operation == 'generate':
                 def capability(size):
@@ -2225,9 +2235,9 @@ def capability(size):
                         return None
                 extra['capability'] = capability
             result = await asyncio.to_thread(getattr(projects, operation), *args, value, ref=key or ref, **extra)
-            if operation in ('generate', 'export', 'listen', 'music'):
+            if operation in ('generate', 'export', 'listen', 'music', 'stems'):
                 await jobs.tick()
-            return reply(result, 201 if operation in ('create', 'generate', 'export', 'listen', 'music') else 200)
+            return reply(result, 201 if operation in ('create', 'generate', 'export', 'listen', 'music', 'stems') else 200)
         return guarded(handler)
 
     for operation, (method, suffix, _) in contract.PROJECT_OPERATIONS.items():
diff --git a/freevideo_engine/agent/schema.py b/freevideo_engine/agent/schema.py
index 905a4d0e..f08e9be8 100644
--- a/freevideo_engine/agent/schema.py
+++ b/freevideo_engine/agent/schema.py
@@ -337,6 +337,20 @@ def music(*, local=False):
         **{'x-job-kind': 'music'})
 
 
+STEMS_FIELDS = dict(
+    clip_id=string(64))
+# False leaves the three parts unplaced: the editor page lays them itself so its own saves never clash with the job's.
+STEMS_LAY = dict(lay={'type': 'boolean', 'default': True})
+
+
+def stems(*, local=False):
+    return obj(dict(kind={'const': 'stems', 'type': 'string'},
+        editor_project=string(34, pattern=r'^e-[0-9a-f]{32}$'),
+        revision=number(1, 2**53 - 1, integer=True),
+        **STEMS_FIELDS, **STEMS_LAY, **common()), ('kind', 'editor_project', 'revision', 'clip_id'),
+        **{'x-job-kind': 'stems'})
+
+
 def image_edit(*, local=False):
     return obj(dict(kind={'const': 'image_edit', 'type': 'string'},
         image=dict(IMAGE, description='The image session to render (POST /images).'),
@@ -347,12 +361,12 @@ def image_edit(*, local=False):
 
 
 KINDS = dict(generate=generate, assemble=assemble, vlm=vlm, enhance=enhance, image=image,
-             export=export, listen=listen, music=music, image_edit=image_edit)
+             export=export, listen=listen, music=music, stems=stems, image_edit=image_edit)
 
 
 def job_schema(*, local=False, refs=False, batch=False):
     # Music scores a joined cut, so it is not a storyboard row.
-    value = {'oneOf': [f(local=local) for kind, f in KINDS.items() if not (batch and kind == 'music')], 'x-discriminator': 'kind',
+    value = {'oneOf': [f(local=local) for kind, f in KINDS.items() if not (batch and kind in ('music', 'stems'))], 'x-discriminator': 'kind',
              'description': 'x-discriminator selects field diagnostics by kind; all accepted branches use standard oneOf.'}
     return batch_references(value) if refs else value
 
@@ -469,7 +483,7 @@ def route(summary, body=None, query=None, **kw):
         if method == 'GET':
             extra['query'] = shape
         else:
-            extra.update(body=shape, idempotent=True, **({'status': 201} if name in ('create', 'generate', 'export', 'listen', 'music') else {}))
+            extra.update(body=shape, idempotent=True, **({'status': 201} if name in ('create', 'generate', 'export', 'listen', 'music', 'stems') else {}))
         routes[method, suffix] = route(summary, **extra)
     for name, (method, suffix, summary) in WHITEBOX_OPERATIONS.items():
         extra = dict(path=obj({'id': WHITEBOX}, ('id',))) if '{id}' in suffix else {}
@@ -546,6 +560,10 @@ def route(summary, body=None, query=None, **kw):
                                             auth=False, page_or_token=True)
     routes['PUT', '/confirmations'] = route('Only the page user may change which operations need approval.',
                                             body=confirm_settings(), auth=False, page_or_token=True)
+    # The editor page separates sound itself: these four also accept its page session, which never holds the token.
+    for key in (('POST', '/projects/{id}/stems'), ('POST', '/projects/{id}/stems/export'),
+                ('GET', '/jobs/{id}'), ('POST', '/jobs/{id}/cancel')):
+        routes[key]['page_ok'] = True
     return routes
 
 
@@ -854,12 +872,15 @@ def image_schema(name):
     'generate': ('POST', '/projects/{id}/generate', 'Make new picture and sound for selected clips or a frame range, as the page Generate does. First get revision and clip IDs; the parts are reserved at once and fill in as the returned job finishes.'),
     'export': ('POST', '/projects/{id}/export', 'Render one saved revision to an MP4 in the saved videos. First get the revision; wait for the returned job, then read its result video.'),
     'listen': ('POST', '/projects/{id}/listen', 'Listen to the timeline sound for subtitles: mode align times lines you give, transcribe writes down what is said. First get the revision; wait for the returned job, then add the lines with the subtitles edit. Nothing is saved; with no speech model for the language the call fails with no_speech_model, so write the lines by hand.'),
+    'stems': ('POST', '/projects/{id}/stems', 'Split one clip\'s sound into dialogue, music and ambience on tracks a4-a6. First get the revision and clip ID; wait for the job, then read result.parts.'),
+    'stems_export': ('POST', '/projects/{id}/stems/export', 'Save the separated dialogue, music and ambience of a split clip, with its original mix, as four wav files in the saved sounds. First get the revision and the split clip\'s ID; the answer lists the files at once.'),
     'music': ('POST', '/projects/{id}/music', 'Compose music as long as the joined cut and lay it on sound track a2 at frame 0, under the video sound. First get the revision; a2 must be empty. Wait for the returned job; the first use downloads the model (20 GB).'),
 }
 PROJECT_TOOLS = dict(list='freevideo_projects', get='freevideo_project_read', create='freevideo_project_create',
                      write='freevideo_project_write', operations='freevideo_editor_operations',
                      generate='freevideo_project_generate', export='freevideo_export',
-                     listen='freevideo_project_listen', music='freevideo_project_music')
+                     listen='freevideo_project_listen', music='freevideo_project_music',
+                     stems='freevideo_project_stems', stems_export='freevideo_project_stems_export')
 
 SESSION_OPERATIONS = {
     'create': ('POST', '/sessions', 'Create a work conversation for messages and plans shared with the user.'),
@@ -980,6 +1001,8 @@ def project_schema(name):
         return obj(dict(revision=revision, **LISTEN_FIELDS, ref=REF), ('revision', 'mode'))
     if name == 'music':
         return obj(dict(revision=revision, **MUSIC_FIELDS, ref=REF), ('revision', 'caption'))
+    if name in ('stems', 'stems_export'):
+        return obj(dict(revision=revision, **STEMS_FIELDS, **(STEMS_LAY if name == 'stems' else {}), ref=REF), ('revision', 'clip_id'))
     if name != 'operations':
         return EMPTY
     fields = {
@@ -1433,6 +1456,8 @@ def openapi():
         if contract.get('raw_body'):
             operation['requestBody'] = dict(required=True, content={'application/octet-stream': {'schema': {
                 'type': 'string', 'format': 'binary', 'maxLength': MAX_CHAT_ATTACHMENT_BYTES}}})
+        if contract.get('page_ok'):
+            operation['security'] = [{'bearer': []}, {'page': []}]
         if contract.get('page_or_token'):
             operation['security'] = [{'page': []}] if suffix.endswith(('/stop', '/resume')) else [{'bearer': []}, {'page': []}]
         if contract['body'] is not None:
@@ -1452,6 +1477,9 @@ def openapi():
         if suffix == '/freevideo/agent/chat/attach':
             operation['parameters'].append(dict(name='X-FreeVideo-CSRF', **{'in': 'header'}, required=True,
                 schema=string(128), description='The page session CSRF token.'))
+        if contract.get('page_ok'):
+            operation['parameters'].append(dict(name='X-FreeVideo-CSRF', **{'in': 'header'}, required=False,
+                schema=string(128), description='With the freevideo_agent_page cookie, in place of the token.'))
         if contract.get('page_or_token'):
             operation['parameters'].append(dict(name='X-FreeVideo-CSRF', **{'in': 'header'}, required=False,
                 schema=string(128), description='Required with the freevideo_agent_page cookie, including reads.'))
diff --git a/freevideo_engine/agent/spec.py b/freevideo_engine/agent/spec.py
index 46846f8d..f19581f8 100644
--- a/freevideo_engine/agent/spec.py
+++ b/freevideo_engine/agent/spec.py
@@ -297,6 +297,9 @@ def normalize(value, *, port=None):
     elif kind == 'music':
         result.update(editor_project=value['editor_project'], revision=value['revision'], caption=value['caption'],
                       **{k: value[k] for k in ('seed', 'quiet') if k in value})
+    elif kind == 'stems':
+        result.update(editor_project=value['editor_project'], revision=value['revision'], clip_id=value['clip_id'],
+                      lay=value.get('lay', True))
     elif kind == 'image_edit':
         result.update(image=value['image'], revision=value['revision'])
     else:
diff --git a/freevideo_engine/agent/stems.py b/freevideo_engine/agent/stems.py
new file mode 100644
index 00000000..cecaa304
--- /dev/null
+++ b/freevideo_engine/agent/stems.py
@@ -0,0 +1,85 @@
+"""Stem jobs: the sound of one clip split into dialogue, music and ambience, laid on three sub-tracks."""
+import json
+import secrets
+import time
+
+from .jobs import JobError
+
+FOLDER = 'freevideo-stems'
+# A video that starts while the sound is split stops it; the job waits for the video and splits again.
+PREEMPTIONS = 8
+NAMES = ('dialogue', 'music', 'ambience')
+
+
+def _busy(jobs):
+    port = jobs.port
+    return jobs.runner_busy() or port.queue_busy() or port.image_busy() or port.vlm_busy()
+
+
+def run_stems(jobs, row, *, poll=.5):
+    from ..editor_export import resolve_source
+    from ..stems import service
+    spec, port = row['spec'], jobs.port
+    try:
+        project = jobs.projects.get(spec['editor_project'])['project']
+    except FileNotFoundError as error:
+        raise JobError('not_found', 'The project does not exist') from error
+    clip = next((clip for track in project['tracks'] if track['kind'] == 'audio' for clip in track['clips']
+                 if clip['id'] == spec['clip_id']), None)
+    if clip is None or not clip.get('source'):
+        raise JobError('invalid_request', 'The clip is not a sound clip with media')
+    try:
+        found = resolve_source('%s:%s' % (clip['source']['kind'], clip['source']['id']))
+    except (OSError, ValueError) as error:
+        raise JobError('stems_failed', 'The clip media is not readable', kind='stems') from error
+    source = found['audio']
+    if source is None:
+        raise JobError('stems_failed', 'The clip has no sound', kind='stems')
+    folder = '%s/%s-%s' % (FOLDER, row['id'], secrets.token_hex(4))
+    out = port.output_path(folder + '/dialogue.mp4', create=True).parent
+
+    def phase(name, fraction=None):
+        row['_phase'] = name
+        row['_detail'] = json.dumps(dict(fraction=round(fraction, 3))) if fraction is not None else None
+
+    try:
+        numbers = _split(jobs, row, service, source, out, phase, poll)
+        sources = {name: 'generated:%s/%s.mp4' % (folder, name) for name in NAMES}
+        if not spec.get('lay', True):
+            return dict(editor_project=spec['editor_project'], clip_id=spec['clip_id'], sources=sources, parts=[], clip_ids=[],
+                        seconds=numbers.get('seconds'), separate_seconds=numbers.get('elapsed'))
+        phase('placing')
+        saved, clip_ids = jobs.projects.lay_stems(spec['editor_project'], spec['clip_id'], sources)
+    except BaseException:
+        for path in out.glob('*'):
+            path.unlink(missing_ok=True)
+        out.rmdir()
+        raise
+    fresh = set(clip_ids)
+    parts = [dict(track=track['id'], name=track['stem'], clip_id=clip['id'], start=clip['start'], frames=clip['frames'],
+                  end=clip['start'] + clip['frames'])
+             for track in saved['tracks'] if track.get('stem') for clip in track['clips'] if clip['id'] in fresh]
+    return dict(editor_project=spec['editor_project'], revision=saved['revision'], clip_ids=clip_ids, sources=sources,
+                parts=parts, seconds=numbers.get('seconds'),
+                separate_seconds=numbers.get('elapsed'))
+
+
+def _split(jobs, row, service, source, out, phase, poll):
+    for attempt in range(PREEMPTIONS + 1):
+        try:
+            return service.separate(source, out, server=getattr(jobs.port, 'server', None),
+                                    cancelled=lambda: bool(row.get('_cancel')), phase=phase)
+        except service.Preempted:
+            if attempt == PREEMPTIONS:
+                raise JobError('stems_failed', 'Videos kept starting while the sound was being split', kind='stems') from None
+            phase('waiting')
+            while True:
+                if row.get('_cancel'):
+                    raise JobError('cancelled', 'Cancelled') from None
+                time.sleep(poll)
+                if not _busy(jobs):
+                    break
+        except InterruptedError:
+            raise JobError('cancelled', 'Cancelled') from None
+        except service.StemsError as error:
+            raise JobError(error.code, 'The sound was not split (%s)' % (error.reason or error.code), kind='stems') from None
diff --git a/freevideo_engine/comfy_editor.py b/freevideo_engine/comfy_editor.py
index 3c6b1995..a6925128 100644
--- a/freevideo_engine/comfy_editor.py
+++ b/freevideo_engine/comfy_editor.py
@@ -30,7 +30,7 @@
 from .editor_limits import PROJECT_BYTES
 from .editor_speed import validate_clip, register_reverse
 from .editor_transport import marker_fields
-from .editor_audio import clip_fields, track_fields
+from .editor_audio import STEM_TRACKS, clip_fields, track_fields
 
 FPS = 24
 MAX_IMPORT_BYTES = 8 * 1024**3
@@ -187,14 +187,16 @@ def bounded(value, depth=0):
     if not _text(json.dumps(settings, ensure_ascii=False, allow_nan=False, separators=(',', ':')), 1024 * 1024):
         raise ValueError('Settings are too large')
     raw_tracks = record.get('tracks')
-    expected = [('v1', 'video'), ('a1', 'audio'), ('a2', 'audio')]
-    if not isinstance(raw_tracks, list) or len(raw_tracks) not in (2, 3):
+    expected = [('v1', 'video'), ('a1', 'audio'), ('a2', 'audio'), ('a3', 'audio'), ('a4', 'audio'), ('a5', 'audio'), ('a6', 'audio')]
+    if not isinstance(raw_tracks, list) or len(raw_tracks) not in (2, 3, 7):
         raise ValueError('Invalid tracks')
     tracks, seen = [], {}
     for raw_track, (track_id, kind) in zip(raw_tracks, expected):
         if (not isinstance(raw_track, dict) or raw_track.get('id') != track_id or raw_track.get('kind') != kind
                 or not isinstance(raw_track.get('clips'), list) or len(raw_track['clips']) > 500):
             raise ValueError('Invalid track')
+        if (raw_track.get('stem') != (STEM_TRACKS[len(tracks) - 4] if len(tracks) >= 4 else None)):
+            raise ValueError('Invalid track')
         clips, end = [], 0
         for raw in raw_track['clips']:
             if not isinstance(raw, dict):
diff --git a/freevideo_engine/comfy_nodes.py b/freevideo_engine/comfy_nodes.py
index 93a12312..9b9b59db 100644
--- a/freevideo_engine/comfy_nodes.py
+++ b/freevideo_engine/comfy_nodes.py
@@ -263,6 +263,11 @@ def execute(cls, text, width, height, seconds, seed, first=None, last=None,
             note('video', path(comfy_bridge.installation_root()))
         except Exception as error:
             logging.warning('[FreeVideo] Could not record the video for the picture worker: %s', error)
+        try:   # nor splitting a clip's sound, which starts again after the video
+            from .stems.service import stop_for_generation as stop_stems_for_generation
+            stop_stems_for_generation(PromptServer.instance)
+        except Exception as error:
+            logging.warning('[FreeVideo] Could not stop sound separation before the video: %s', error)
         prewarm = {}
         result_reused = [False]
         result_report = [None]
diff --git a/freevideo_engine/comfy_progress.py b/freevideo_engine/comfy_progress.py
index fd6174d4..e1226ea5 100644
--- a/freevideo_engine/comfy_progress.py
+++ b/freevideo_engine/comfy_progress.py
@@ -428,6 +428,19 @@ async def feedback_info(request):
         info = await asyncio.to_thread(feedback.collect, request.query.get('report_id'))
         return web.json_response(info, headers={'Cache-Control': 'no-store'})
 
+    @server.routes.get('/freevideo/stems-support')
+    async def stems_support(request):
+        # The editor page asks once whether to offer sound separation; the agent feature list needs a token the page never holds.
+        def offered():
+            from .agent.editor_runtime import available
+            from .agent.routes import stems_supported
+            from .comfy_bridge import installation
+            try:
+                return bool(available() and stems_supported(installation()[1]))
+            except (OSError, ValueError):
+                return False
+        return web.json_response({'available': await asyncio.to_thread(offered)}, headers={'Cache-Control': 'no-store'})
+
     @server.routes.get('/freevideo/progress')
     async def progress(request):
         return web.json_response({'progress': STATE.snapshot()},
diff --git a/freevideo_engine/editor_audio.py b/freevideo_engine/editor_audio.py
index ab605d8f..30af9fd9 100644
--- a/freevideo_engine/editor_audio.py
+++ b/freevideo_engine/editor_audio.py
@@ -4,6 +4,8 @@
 
 from .editor_speed import changed, audio_changed, source_sample_start
 
+STEM_TRACKS = ('dialogue', 'music', 'ambience')
+
 
 def clip_fields(raw, kind):
     result = {}
@@ -29,6 +31,17 @@ def clip_fields(raw, kind):
         if kind != 'audio' or type(raw['duck']) is not bool:
             raise ValueError('Invalid audio ducking')
         result['duck'] = raw['duck']
+    if 'stem_of' in raw:
+        value = raw['stem_of']
+        if (kind != 'audio' or not isinstance(value, str) or not re.fullmatch(r'c[1-9]\d{0,8}', value)
+                or value == raw['id'] or raw.get('link')):
+            raise ValueError('Invalid separated sound')
+        result['stem_of'] = value
+    if 'stem_volume' in raw:
+        value = raw['stem_volume']
+        if kind != 'audio' or type(value) not in (int, float) or not 0 <= value <= 2:
+            raise ValueError('Invalid separated sound')
+        result['stem_volume'] = value
     return result
 
 
@@ -39,6 +52,10 @@ def track_fields(raw):
             if type(raw[name]) is not bool:
                 raise ValueError('Invalid audio track flag')
             result[name] = raw[name]
+    if 'stem' in raw:
+        if raw['stem'] not in STEM_TRACKS:
+            raise ValueError('Invalid audio track flag')
+        result['stem'] = raw['stem']
     return result
 
 
diff --git a/freevideo_engine/editor_export.py b/freevideo_engine/editor_export.py
index 01a0659c..9517c45c 100644
--- a/freevideo_engine/editor_export.py
+++ b/freevideo_engine/editor_export.py
@@ -113,7 +113,7 @@ def _layout(project):
         project = validate(project)
         raw_tracks = [t for t in project['tracks'] if not is_text_track(t)]
     if not isinstance(raw_tracks, list) or [t.get('id') for t in raw_tracks if isinstance(t, dict)] not in (
-            ['v1', 'a1'], ['v1', 'a1', 'a2']):
+            ['v1', 'a1'], ['v1', 'a1', 'a2'], ['v1', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6']):
         raise ExportError()
     tracks, seen = {}, set()
     for raw in raw_tracks:
@@ -777,7 +777,7 @@ def save_lead(lead):
                         if progress:
                             progress(written / total * .99)
                 mixed = np.zeros((2, SAMPLES_PER_FRAME), dtype=np.float32)
-                for track in ('a1', 'a2'):
+                for track in ('a1', 'a2', 'a3', 'a4', 'a5', 'a6'):
                     clip = active.get(track)
                     if track not in audio_tracks:
                         continue
diff --git a/freevideo_engine/editor_text.py b/freevideo_engine/editor_text.py
index 8e768924..a38a0c7c 100644
--- a/freevideo_engine/editor_text.py
+++ b/freevideo_engine/editor_text.py
@@ -91,7 +91,7 @@ def validate_text_project(raw, validate_media):
         if row['clips']: result['tracks'].append(row)
     style = clean_style(raw.get('subtitle_style',{}),'subtitle')
     if style and any(t['kind'] == 'subtitle' for t in result['tracks']): result['subtitle_style'] = style
-    result['tracks'].sort(key=lambda t: ['v1','a1','a2','t1','s1'].index(t['id']))
+    result['tracks'].sort(key=lambda t: ['v1','a1','a2','a3','a4','a5','a6','t1','s1'].index(t['id']))
     return result
 
 
diff --git a/freevideo_engine/image_gen/image_models.json b/freevideo_engine/image_gen/image_models.json
index 86f7f861..269cae28 100644
--- a/freevideo_engine/image_gen/image_models.json
+++ b/freevideo_engine/image_gen/image_models.json
@@ -685,6 +685,27 @@
           }
         ]
       }
+    ],
+    "stems": [
+      {
+        "file": "stems/bandit_plus_cocktail.pt",
+        "component": "stems",
+        "bytes": 148724733,
+        "sha256": "02ad94875ae060e03428af0e667a5a5cbfa1a6c2355f07f32c499be8d615ba1c",
+        "repo": "BowenXue/FreeVideo-models",
+        "revision": "2ed0b3b98ea92dec01699dc97d96e15cfe208d69",
+        "model_id": "bandit-plus-cocktail",
+        "sources": [
+          {
+            "id": "official",
+            "url": "https://huggingface.co/BowenXue/FreeVideo-models/resolve/2ed0b3b98ea92dec01699dc97d96e15cfe208d69/stems/bandit_plus_cocktail.pt"
+          },
+          {
+            "id": "modelscope",
+            "url": "https://www.modelscope.cn/models/BowenXue/FreeVideo-models/resolve/master/stems/bandit_plus_cocktail.pt"
+          }
+        ]
+      }
     ]
   }
 }
diff --git a/freevideo_engine/image_gen/image_pack.py b/freevideo_engine/image_gen/image_pack.py
index 4fdd0c33..2308bbbe 100644
--- a/freevideo_engine/image_gen/image_pack.py
+++ b/freevideo_engine/image_gen/image_pack.py
@@ -140,7 +140,7 @@ def validate_catalog(spec):
             raise PackError('invalid_catalog')
         image_rows = spec['groups']['image']
         # A group of its own holds only its own component; the image group holds neither.
-        own = {group: spec['groups'].get(group, []) for group in ('segment', 'music')}
+        own = {group: spec['groups'].get(group, []) for group in ('segment', 'music', 'stems')}
         found = image_rows + [row for found in own.values() for row in found]
         if (not image_rows or len({r['file'] for r in found}) != len(found) or set(spec['groups']) - {'image', *own}
                 or any(row['component'] in own for row in image_rows)
@@ -150,7 +150,7 @@ def validate_catalog(spec):
             _relative(row['file'])
             if (type(row['bytes']) is not int or row['bytes'] <= 0
                     or not re.fullmatch('[0-9a-f]{64}', row['sha256'])
-                    or row['component'] not in ('dit', 'text_encoder', 'vae', 'text_encoder_config', 'processor', 'segment', 'music')):
+                    or row['component'] not in ('dit', 'text_encoder', 'vae', 'text_encoder_config', 'processor', 'segment', 'music', 'stems')):
                 raise PackError('invalid_catalog')
             ids = [s['id'] for s in row['sources']]
             required = {'official', 'modelscope'}
@@ -233,8 +233,13 @@ def _owned_intact(path, stamp):
                      b'freevideo_engine/licenses/Qwen3-Embedding-Apache-2.0.txt.\nhttps://huggingface.co/Qwen/Qwen3-Embedding-0.6B\n'
                      b'Silero VAD, Copyright (c) 2020-present Silero Team. Licensed under the MIT License; see '
                      b'freevideo_engine/licenses/Silero-VAD-MIT.txt.\nhttps://github.com/snakers4/silero-vad\n')
+STEMS_NOTICE_TEXT = (b'Bandit Plus (cocktail-party separation model). Weights: Watcharasupat et al., CC BY-NC 4.0; see '
+                     b'freevideo_engine/licenses/Bandit-CC-BY-NC-4.0.txt.\nhttps://zenodo.org/records/10160698\n'
+                     b'Code: Copyright (c) the Bandit authors, Apache-2.0; see freevideo_engine/licenses/Bandit-Apache-2.0.txt.\n'
+                     b'https://github.com/kwatcharasupat/source-separation\n')
 NOTICES = {'image': ('NOTICE.txt', NOTICE_TEXT), 'segment': ('SAM2-NOTICE.txt', SEGMENT_NOTICE_TEXT),
-           'music': ('MUSIC-NOTICE.txt', MUSIC_NOTICE_TEXT)}
+           'music': ('MUSIC-NOTICE.txt', MUSIC_NOTICE_TEXT),
+           'stems': ('STEMS-NOTICE.txt', STEMS_NOTICE_TEXT)}
 
 
 def _notice():
@@ -929,7 +934,7 @@ def main(argv=None):
     commands = parser.add_subparsers(dest='command', required=True)
     download = commands.add_parser('download')
     download.add_argument('--background', action='store_true')
-    download.add_argument('--group', choices=('image', 'segment'), default='image')
+    download.add_argument('--group', choices=('image', 'segment', 'music', 'stems'), default='image')
     download.add_argument('--root', type=Path)
     download.add_argument('--engine-root', type=Path)
     download.add_argument('--status-file', type=Path, required=True)
diff --git a/freevideo_engine/licenses/Bandit-Apache-2.0.txt b/freevideo_engine/licenses/Bandit-Apache-2.0.txt
new file mode 100644
index 00000000..3b6e7a43
--- /dev/null
+++ b/freevideo_engine/licenses/Bandit-Apache-2.0.txt
@@ -0,0 +1,207 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction, and
+    distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by the
+    copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all other
+    entities that control, are controlled by, or are under common control with
+    that entity. For the purposes of this definition, "control" means (i) the
+    power, direct or indirect, to cause the direction or management of such
+    entity, whether by contract or otherwise, or (ii) ownership of
+    fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+    ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity exercising
+    permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation source,
+    and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical transformation
+    or translation of a Source form, including but not limited to compiled
+    object code, generated documentation, and conversions to
+    other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or Object
+    form, made available under the License, as indicated by a copyright notice
+    that is included in or attached to the work (an example is provided in the
+    Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object form,
+    that is based on (or derived from) the Work and for which the editorial
+    revisions, annotations, elaborations, or other modifications represent,
+    as a whole, an original work of authorship. For the purposes of this
+    License, Derivative Works shall not include works that remain separable
+    from, or merely link (or bind by name) to the interfaces of, the Work and
+    Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including the original
+    version of the Work and any modifications or additions to that Work or
+    Derivative Works thereof, that is intentionally submitted to Licensor for
+    inclusion in the Work by the copyright owner or by an individual or
+    Legal Entity authorized to submit on behalf of the copyright owner.
+    For the purposes of this definition, "submitted" means any form of
+    electronic, verbal, or written communication sent to the Licensor or its
+    representatives, including but not limited to communication on electronic
+    mailing lists, source code control systems, and issue tracking systems
+    that are managed by, or on behalf of, the Licensor for the purpose of
+    discussing and improving the Work, but excluding communication that is
+    conspicuously marked or otherwise designated in writing by the copyright
+    owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity on
+    behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+    Subject to the terms and conditions of this License, each Contributor
+    hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+    royalty-free, irrevocable copyright license to reproduce, prepare
+    Derivative Works of, publicly display, publicly perform, sublicense,
+    and distribute the Work and such Derivative Works in
+    Source or Object form.
+
+3. Grant of Patent License.
+
+    Subject to the terms and conditions of this License, each Contributor
+    hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+    royalty-free, irrevocable (except as stated in this section) patent
+    license to make, have made, use, offer to sell, sell, import, and
+    otherwise transfer the Work, where such license applies only to those
+    patent claims licensable by such Contributor that are necessarily
+    infringed by their Contribution(s) alone or by combination of their
+    Contribution(s) with the Work to which such Contribution(s) was submitted.
+    If You institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+    Contribution incorporated within the Work constitutes direct or
+    contributory patent infringement, then any patent licenses granted to
+    You under this License for that Work shall terminate as of the date such
+    litigation is filed.
+
+4. Redistribution.
+
+    You may reproduce and distribute copies of the Work or Derivative Works
+    thereof in any medium, with or without modifications, and in Source or
+    Object form, provided that You meet the following conditions:
+
+    1. You must give any other recipients of the Work or Derivative Works a
+    copy of this License; and
+
+    2. You must cause any modified files to carry prominent notices stating
+    that You changed the files; and
+
+    3. You must retain, in the Source form of any Derivative Works that You
+    distribute, all copyright, patent, trademark, and attribution notices from
+    the Source form of the Work, excluding those notices that do not pertain
+    to any part of the Derivative Works; and
+
+    4. If the Work includes a "NOTICE" text file as part of its distribution,
+    then any Derivative Works that You distribute must include a readable copy
+    of the attribution notices contained within such NOTICE file, excluding
+    those notices that do not pertain to any part of the Derivative Works,
+    in at least one of the following places: within a NOTICE text file
+    distributed as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or, within a
+    display generated by the Derivative Works, if and wherever such
+    third-party notices normally appear. The contents of the NOTICE file are
+    for informational purposes only and do not modify the License.
+    You may add Your own attribution notices within Derivative Works that You
+    distribute, alongside or as an addendum to the NOTICE text from the Work,
+    provided that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and may
+    provide additional or different license terms and conditions for use,
+    reproduction, or distribution of Your modifications, or for any such
+    Derivative Works as a whole, provided Your use, reproduction, and
+    distribution of the Work otherwise complies with the conditions
+    stated in this License.
+
+5. Submission of Contributions.
+
+    Unless You explicitly state otherwise, any Contribution intentionally
+    submitted for inclusion in the Work by You to the Licensor shall be under
+    the terms and conditions of this License, without any additional
+    terms or conditions. Notwithstanding the above, nothing herein shall
+    supersede or modify the terms of any separate license agreement you may
+    have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+
+    This License does not grant permission to use the trade names, trademarks,
+    service marks, or product names of the Licensor, except as required for
+    reasonable and customary use in describing the origin of the Work and
+    reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+    Unless required by applicable law or agreed to in writing, Licensor
+    provides the Work (and each Contributor provides its Contributions)
+    on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+    either express or implied, including, without limitation, any warranties
+    or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS
+    FOR A PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any risks
+    associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability.
+
+    In no event and under no legal theory, whether in tort
+    (including negligence), contract, or otherwise, unless required by
+    applicable law (such as deliberate and grossly negligent acts) or agreed
+    to in writing, shall any Contributor be liable to You for damages,
+    including any direct, indirect, special, incidental, or consequential
+    damages of any character arising as a result of this License or out of
+    the use or inability to use the Work (including but not limited to damages
+    for loss of goodwill, work stoppage, computer failure or malfunction,
+    or any and all other commercial damages or losses), even if such
+    Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+    While redistributing the Work or Derivative Works thereof, You may choose
+    to offer, and charge a fee for, acceptance of support, warranty,
+    indemnity, or other liability obligations and/or rights consistent with
+    this License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf of any
+    other Contributor, and only if You agree to indemnify, defend, and hold
+    each Contributor harmless for any liability incurred by, or claims
+    asserted against, such Contributor by reason of your accepting any such
+    warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+    To apply the Apache License to your work, attach the following boilerplate
+    notice, with the fields enclosed by brackets "[]" replaced with your own
+    identifying information. (Don't include the brackets!) The text should be
+    enclosed in the appropriate comment syntax for the file format. We also
+    recommend that a file or class name and description of purpose be included
+    on the same "printed page" as the copyright notice for easier
+    identification within third-party archives.
+
+        Copyright {{ year }} {{ organization }}
+
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+        or implied. See the License for the specific language governing
+        permissions and limitations under the License.
diff --git a/freevideo_engine/licenses/Bandit-CC-BY-NC-4.0.txt b/freevideo_engine/licenses/Bandit-CC-BY-NC-4.0.txt
new file mode 100644
index 00000000..b90ca830
--- /dev/null
+++ b/freevideo_engine/licenses/Bandit-CC-BY-NC-4.0.txt
@@ -0,0 +1,10 @@
+Bandit Plus cocktail-party separation weights (speech / music / effects).
+
+Credit: Karn N. Watcharasupat, Chih-Wei Wu, Iroro Orife, "Divide and Remaster / Banquet / Bandit:
+Source Separation for the Cocktail Party Problem" (Bandit, Bandit Plus), and the Divide and Remaster
+v3 dataset authors. Weights released at https://zenodo.org/records/10160698
+Code: https://github.com/kwatcharasupat/source-separation (Apache-2.0, see Bandit-Apache-2.0.txt).
+
+The weights are licensed under the Creative Commons Attribution-NonCommercial 4.0 International
+License (CC BY-NC 4.0): https://creativecommons.org/licenses/by-nc/4.0/legalcode
+FreeVideo converts the checkpoint to a plain state dictionary without changing any value.
diff --git a/freevideo_engine/stems/__init__.py b/freevideo_engine/stems/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/freevideo_engine/stems/bandit/__init__.py b/freevideo_engine/stems/bandit/__init__.py
new file mode 100644
index 00000000..8633475c
--- /dev/null
+++ b/freevideo_engine/stems/bandit/__init__.py
@@ -0,0 +1,2 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
diff --git a/freevideo_engine/stems/bandit/bandsplit.py b/freevideo_engine/stems/bandit/bandsplit.py
new file mode 100644
index 00000000..c09876e3
--- /dev/null
+++ b/freevideo_engine/stems/bandit/bandsplit.py
@@ -0,0 +1,141 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+from typing import List, Tuple
+
+import torch
+from torch import nn
+
+from .utils import (
+    band_widths_from_specs,
+    check_no_gap,
+    check_no_overlap,
+    check_nonzero_bandwidth,
+)
+
+
+class NormFC(nn.Module):
+    def __init__(
+            self,
+            emb_dim: int,
+            bandwidth: int,
+            in_channel: int,
+            normalize_channel_independently: bool = False,
+            treat_channel_as_feature: bool = True,
+    ) -> None:
+        super().__init__()
+
+        self.treat_channel_as_feature = treat_channel_as_feature
+
+        if normalize_channel_independently:
+            raise NotImplementedError
+
+        reim = 2
+
+        self.norm = nn.LayerNorm(in_channel * bandwidth * reim)
+
+        fc_in = bandwidth * reim
+
+        if treat_channel_as_feature:
+            fc_in *= in_channel
+        else:
+            assert emb_dim % in_channel == 0
+            emb_dim = emb_dim // in_channel
+
+        self.fc = nn.Linear(fc_in, emb_dim)
+
+    def forward(self, xb):
+        # xb = (batch, n_time, in_chan, reim * band_width)
+
+        batch, n_time, in_chan, ribw = xb.shape
+        xb = self.norm(xb.reshape(batch, n_time, in_chan * ribw))
+        # (batch, n_time, in_chan * reim * band_width)
+
+        if not self.treat_channel_as_feature:
+            xb = xb.reshape(batch, n_time, in_chan, ribw)
+            # (batch, n_time, in_chan, reim * band_width)
+
+        zb = self.fc(xb)
+        # (batch, n_time, emb_dim)
+        # OR
+        # (batch, n_time, in_chan, emb_dim_per_chan)
+
+        if not self.treat_channel_as_feature:
+            batch, n_time, in_chan, emb_dim_per_chan = zb.shape
+            # (batch, n_time, in_chan, emb_dim_per_chan)
+            zb = zb.reshape((batch, n_time, in_chan * emb_dim_per_chan))
+
+        return zb  # (batch, n_time, emb_dim)
+
+
+class BandSplitModule(nn.Module):
+    def __init__(
+            self,
+            band_specs: List[Tuple[float, float]],
+            emb_dim: int,
+            in_channel: int,
+            require_no_overlap: bool = False,
+            require_no_gap: bool = True,
+            normalize_channel_independently: bool = False,
+            treat_channel_as_feature: bool = True,
+    ) -> None:
+        super().__init__()
+
+        check_nonzero_bandwidth(band_specs)
+
+        if require_no_gap:
+            check_no_gap(band_specs)
+
+        if require_no_overlap:
+            check_no_overlap(band_specs)
+
+        self.band_specs = band_specs
+        # list of [fstart, fend) in index.
+        # Note that fend is exclusive.
+        self.band_widths = band_widths_from_specs(band_specs)
+        self.n_bands = len(band_specs)
+        self.emb_dim = emb_dim
+
+        self.norm_fc_modules = nn.ModuleList(
+                [  # type: ignore
+                        (
+                                NormFC(
+                                        emb_dim=emb_dim,
+                                        bandwidth=bw,
+                                        in_channel=in_channel,
+                                        normalize_channel_independently=normalize_channel_independently,
+                                        treat_channel_as_feature=treat_channel_as_feature,
+                                )
+                        )
+                        for bw in self.band_widths
+                ]
+        )
+
+    def forward(self, x: torch.Tensor):
+        # x = complex spectrogram (batch, in_chan, n_freq, n_time)
+
+        batch, in_chan, _, n_time = x.shape
+
+        z = torch.zeros(
+            size=(batch, self.n_bands, n_time, self.emb_dim),
+            device=x.device
+        )
+
+        xr = torch.view_as_real(x)  # batch, in_chan, n_freq, n_time, 2
+        xr = torch.permute(
+            xr,
+            (0, 3, 1, 4, 2)
+            )  # batch, n_time, in_chan, 2, n_freq
+        batch, n_time, in_chan, reim, band_width = xr.shape
+        for i, nfm in enumerate(self.norm_fc_modules):
+            # print(f"bandsplit/band{i:02d}")
+            fstart, fend = self.band_specs[i]
+            xb = xr[..., fstart:fend]
+            # (batch, n_time, in_chan, reim, band_width)
+            xb = torch.reshape(xb, (batch, n_time, in_chan, -1))
+            # (batch, n_time, in_chan, reim * band_width)
+            # z.append(nfm(xb))  # (batch, n_time, emb_dim)
+            z[:, i, :, :] = nfm(xb.contiguous())
+
+        # z = torch.stack(z, dim=1)
+
+        return z
diff --git a/freevideo_engine/stems/bandit/base.py b/freevideo_engine/stems/bandit/base.py
new file mode 100644
index 00000000..32cf48c2
--- /dev/null
+++ b/freevideo_engine/stems/bandit/base.py
@@ -0,0 +1,20 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+from abc import ABC
+from typing import Iterable, Mapping, Union
+
+from torch import nn
+
+
+
+class BandsplitCoreBase(nn.Module, ABC):
+    band_split: nn.Module
+    tf_model: nn.Module
+    mask_estim: Union[nn.Module, Mapping[str, nn.Module], Iterable[nn.Module]]
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    @staticmethod
+    def mask(x, m):
+        return x * m
diff --git a/freevideo_engine/stems/bandit/core.py b/freevideo_engine/stems/bandit/core.py
new file mode 100644
index 00000000..83b3e3c4
--- /dev/null
+++ b/freevideo_engine/stems/bandit/core.py
@@ -0,0 +1,236 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+from typing import Dict, List, Optional, Tuple
+
+import torch
+from torch import nn
+
+from .base import BandsplitCoreBase
+from .bandsplit import BandSplitModule
+from .maskestim import (
+    MaskEstimationModule,
+    OverlappingMaskEstimationModule
+)
+from .tfmodel import SeqBandModellingModule
+
+
+class MultiMaskBandSplitCoreBase(BandsplitCoreBase):
+    def __init__(self) -> None:
+        super().__init__()
+
+    def forward(self, x, cond=None, compute_residual: bool = True):
+        # x = complex spectrogram (batch, in_chan, n_freq, n_time)
+        # print(x.shape)
+        batch, in_chan, n_freq, n_time = x.shape
+        x = torch.reshape(x, (-1, 1, n_freq, n_time))
+
+        z = self.band_split(x)  # (batch, emb_dim, n_band, n_time)
+
+        # if torch.any(torch.isnan(z)):
+        #     raise ValueError("z nan")
+
+        # print(z)
+        q = self.tf_model(z)  # (batch, emb_dim, n_band, n_time)
+        # print(q)
+
+
+        # if torch.any(torch.isnan(q)):
+        #     raise ValueError("q nan")
+
+        out = {}
+
+        for stem, mem in self.mask_estim.items():
+            m = mem(q, cond=cond)
+
+            # if torch.any(torch.isnan(m)):
+            #     raise ValueError("m nan", stem)
+
+            s = self.mask(x, m)
+            s = torch.reshape(s, (batch, in_chan, n_freq, n_time))
+            out[stem] = s
+
+        return {"spectrogram": out}
+
+    
+
+    def instantiate_mask_estim(self, 
+                               in_channel: int,
+                               stems: List[str],
+                               band_specs: List[Tuple[float, float]],
+                               emb_dim: int,
+                               mlp_dim: int,
+                               cond_dim: int,
+                               hidden_activation: str,
+                                
+                                hidden_activation_kwargs: Optional[Dict] = None,
+                                complex_mask: bool = True,
+                                overlapping_band: bool = False,
+                                freq_weights: Optional[List[torch.Tensor]] = None,
+                                n_freq: Optional[int] = None,
+                                use_freq_weights: bool = True,
+                                mult_add_mask: bool = False
+                                ):
+        if hidden_activation_kwargs is None:
+            hidden_activation_kwargs = {}
+
+        if "mne:+" in stems:
+            stems = [s for s in stems if s != "mne:+"]
+
+        if overlapping_band:
+            assert freq_weights is not None
+            assert n_freq is not None
+
+            self.mask_estim = nn.ModuleDict(
+                    {
+                            stem: OverlappingMaskEstimationModule(
+                                    band_specs=band_specs,
+                                    freq_weights=freq_weights,
+                                    n_freq=n_freq,
+                                    emb_dim=emb_dim,
+                                    mlp_dim=mlp_dim,
+                                    in_channel=in_channel,
+                                    hidden_activation=hidden_activation,
+                                    hidden_activation_kwargs=hidden_activation_kwargs,
+                                    complex_mask=complex_mask,
+                                    use_freq_weights=use_freq_weights,
+                            )
+                            for stem in stems
+                    }
+            )
+        else:
+            self.mask_estim = nn.ModuleDict(
+                    {
+                            stem: MaskEstimationModule(
+                                    band_specs=band_specs,
+                                    emb_dim=emb_dim,
+                                    mlp_dim=mlp_dim,
+                                    cond_dim=cond_dim,
+                                    in_channel=in_channel,
+                                    hidden_activation=hidden_activation,
+                                    hidden_activation_kwargs=hidden_activation_kwargs,
+                                    complex_mask=complex_mask,
+                            )
+                            for stem in stems
+                    }
+            )
+
+    def instantiate_bandsplit(self, 
+                              in_channel: int,
+                              band_specs: List[Tuple[float, float]],
+                              require_no_overlap: bool = False,
+                              require_no_gap: bool = True,
+                              normalize_channel_independently: bool = False,
+                              treat_channel_as_feature: bool = True,
+                              emb_dim: int = 128
+                              ):
+        self.band_split = BandSplitModule(
+                        in_channel=in_channel,
+                        band_specs=band_specs,
+                        require_no_overlap=require_no_overlap,
+                        require_no_gap=require_no_gap,
+                        normalize_channel_independently=normalize_channel_independently,
+                        treat_channel_as_feature=treat_channel_as_feature,
+                        emb_dim=emb_dim,
+                )
+
+
+
+
+
+
+
+class MultiSourceMultiMaskBandSplitCoreRNN(MultiMaskBandSplitCoreBase):
+    def __init__(
+            self,
+            in_channel: int,
+            stems: List[str],
+            band_specs: List[Tuple[float, float]],
+            require_no_overlap: bool = False,
+            require_no_gap: bool = True,
+            normalize_channel_independently: bool = False,
+            treat_channel_as_feature: bool = True,
+            n_sqm_modules: int = 12,
+            emb_dim: int = 128,
+            rnn_dim: int = 256,
+            bidirectional: bool = True,
+            rnn_type: str = "LSTM",
+            mlp_dim: int = 512,
+            cond_dim: int = 0,
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs: Optional[Dict] = None,
+            complex_mask: bool = True,
+            overlapping_band: bool = False,
+            freq_weights: Optional[List[torch.Tensor]] = None,
+            n_freq: Optional[int] = None,
+            use_freq_weights: bool = True,
+            mult_add_mask: bool = False
+    ) -> None:
+
+        super().__init__()
+        self.instantiate_bandsplit(
+                in_channel=in_channel,
+                band_specs=band_specs,
+                require_no_overlap=require_no_overlap,
+                require_no_gap=require_no_gap,
+                normalize_channel_independently=normalize_channel_independently,
+                treat_channel_as_feature=treat_channel_as_feature,
+                emb_dim=emb_dim
+        )
+
+        
+        self.tf_model = (
+                SeqBandModellingModule(
+                        n_modules=n_sqm_modules,
+                        emb_dim=emb_dim,
+                        rnn_dim=rnn_dim,
+                        bidirectional=bidirectional,
+                        rnn_type=rnn_type,
+                )
+        )
+
+        self.mult_add_mask = mult_add_mask
+
+        self.instantiate_mask_estim(
+                in_channel=in_channel,
+                stems=stems,
+                band_specs=band_specs,
+                emb_dim=emb_dim,
+                mlp_dim=mlp_dim,
+                cond_dim=cond_dim,
+                hidden_activation=hidden_activation,
+                hidden_activation_kwargs=hidden_activation_kwargs,
+                complex_mask=complex_mask,
+                overlapping_band=overlapping_band,
+                freq_weights=freq_weights,
+                n_freq=n_freq,
+                use_freq_weights=use_freq_weights,
+                mult_add_mask=mult_add_mask
+        )
+
+    @staticmethod
+    def _mult_add_mask(x, m):
+
+        assert m.ndim == 5
+
+        mm = m[..., 0]
+        am = m[..., 1]
+
+        # print(mm.shape, am.shape, x.shape, m.shape)
+
+        return x * mm + am
+
+    def mask(self, x, m):
+        if self.mult_add_mask:
+
+            return self._mult_add_mask(x, m)
+        else:
+            return super().mask(x, m)
+
+
+
+
+
+
+
+
+
diff --git a/freevideo_engine/stems/bandit/maskestim.py b/freevideo_engine/stems/bandit/maskestim.py
new file mode 100644
index 00000000..244f5e66
--- /dev/null
+++ b/freevideo_engine/stems/bandit/maskestim.py
@@ -0,0 +1,348 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+from typing import Dict, List, Optional, Tuple, Type
+
+import torch
+from torch import nn
+from torch.nn.modules import activation
+
+from .utils import (
+    band_widths_from_specs,
+    check_no_gap,
+    check_no_overlap,
+    check_nonzero_bandwidth,
+)
+
+
+class BaseNormMLP(nn.Module):
+    def __init__(
+            self,
+            emb_dim: int,
+            mlp_dim: int,
+            bandwidth: int,
+            in_channel: Optional[int],
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs=None,
+            complex_mask: bool = True, ):
+
+        super().__init__()
+        if hidden_activation_kwargs is None:
+            hidden_activation_kwargs = {}
+        self.hidden_activation_kwargs = hidden_activation_kwargs
+        self.norm = nn.LayerNorm(emb_dim)
+        self.hidden = torch.jit.script(nn.Sequential(
+                nn.Linear(in_features=emb_dim, out_features=mlp_dim),
+                activation.__dict__[hidden_activation](
+                        **self.hidden_activation_kwargs
+                ),
+        ))
+
+        self.bandwidth = bandwidth
+        self.in_channel = in_channel
+
+        self.complex_mask = complex_mask
+        self.reim = 2 if complex_mask else 1
+        self.glu_mult = 2
+
+
+class NormMLP(BaseNormMLP):
+    def __init__(
+            self,
+            emb_dim: int,
+            mlp_dim: int,
+            bandwidth: int,
+            in_channel: Optional[int],
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs=None,
+            complex_mask: bool = True,
+    ) -> None:
+        super().__init__(
+                emb_dim=emb_dim,
+                mlp_dim=mlp_dim,
+                bandwidth=bandwidth,
+                in_channel=in_channel,
+                hidden_activation=hidden_activation,
+                hidden_activation_kwargs=hidden_activation_kwargs,
+                complex_mask=complex_mask,
+        )
+
+        self.output = torch.jit.script(
+                nn.Sequential(
+                        nn.Linear(
+                                in_features=mlp_dim,
+                                out_features=bandwidth * in_channel * self.reim * 2,
+                        ),
+                        nn.GLU(dim=-1),
+                )
+        )
+
+    def reshape_output(self, mb):
+        # print(mb.shape)
+        batch, n_time, _ = mb.shape
+        if self.complex_mask:
+            mb = mb.reshape(
+                    batch,
+                    n_time,
+                    self.in_channel,
+                    self.bandwidth,
+                    self.reim
+            ).contiguous()
+            # print(mb.shape)
+            mb = torch.view_as_complex(
+                    mb
+            )  # (batch, n_time, in_channel, bandwidth)
+        else:
+            mb = mb.reshape(batch, n_time, self.in_channel, self.bandwidth)
+
+        mb = torch.permute(
+                mb,
+                (0, 2, 3, 1)
+        )  # (batch, in_channel, bandwidth, n_time)
+
+        return mb
+
+    def forward(self, qb):
+        # qb = (batch, n_time, emb_dim)
+
+        # if torch.any(torch.isnan(qb)):
+        #     raise ValueError("qb0")
+
+
+        qb = self.norm(qb)  # (batch, n_time, emb_dim)
+
+        # if torch.any(torch.isnan(qb)):
+        #     raise ValueError("qb1")
+
+        qb = self.hidden(qb)  # (batch, n_time, mlp_dim)
+        # if torch.any(torch.isnan(qb)):
+        #     raise ValueError("qb2")
+        mb = self.output(qb)  # (batch, n_time, bandwidth * in_channel * reim)
+        # if torch.any(torch.isnan(qb)):
+        #     raise ValueError("mb")
+        mb = self.reshape_output(mb)  # (batch, in_channel, bandwidth, n_time)
+
+        return mb
+
+
+class MultAddNormMLP(NormMLP):
+    def __init__(self, emb_dim: int, mlp_dim: int, bandwidth: int, in_channel: int | None, hidden_activation: str = "Tanh", hidden_activation_kwargs=None, complex_mask: bool = True) -> None:
+        super().__init__(emb_dim, mlp_dim, bandwidth, in_channel, hidden_activation, hidden_activation_kwargs, complex_mask)
+
+        self.output2 = torch.jit.script(
+                nn.Sequential(
+                        nn.Linear(
+                                in_features=mlp_dim,
+                                out_features=bandwidth * in_channel * self.reim * 2,
+                        ),
+                        nn.GLU(dim=-1),
+                )
+        )
+
+    def forward(self, qb):
+
+        qb = self.norm(qb)  # (batch, n_time, emb_dim)
+        qb = self.hidden(qb)  # (batch, n_time, mlp_dim)
+        mmb = self.output(qb)  # (batch, n_time, bandwidth * in_channel * reim)
+        mmb = self.reshape_output(mmb)  # (batch, in_channel, bandwidth, n_time)
+        amb = self.output2(qb)  # (batch, n_time, bandwidth * in_channel * reim)
+        amb = self.reshape_output(amb)  # (batch, in_channel, bandwidth, n_time)
+
+        return mmb, amb
+
+
+class MaskEstimationModuleSuperBase(nn.Module):
+    pass
+
+
+class MaskEstimationModuleBase(MaskEstimationModuleSuperBase):
+    def __init__(
+            self,
+            band_specs: List[Tuple[float, float]],
+            emb_dim: int,
+            mlp_dim: int,
+            in_channel: Optional[int],
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs: Dict = None,
+            complex_mask: bool = True,
+            norm_mlp_cls: Type[nn.Module] = NormMLP,
+            norm_mlp_kwargs: Dict = None,
+    ) -> None:
+        super().__init__()
+
+        self.band_widths = band_widths_from_specs(band_specs)
+        self.n_bands = len(band_specs)
+
+        if hidden_activation_kwargs is None:
+            hidden_activation_kwargs = {}
+
+        if norm_mlp_kwargs is None:
+            norm_mlp_kwargs = {}
+
+        self.norm_mlp = nn.ModuleList(
+                [
+                        (
+                                norm_mlp_cls(
+                                        bandwidth=self.band_widths[b],
+                                        emb_dim=emb_dim,
+                                        mlp_dim=mlp_dim,
+                                        in_channel=in_channel,
+                                        hidden_activation=hidden_activation,
+                                        hidden_activation_kwargs=hidden_activation_kwargs,
+                                        complex_mask=complex_mask,
+                                        **norm_mlp_kwargs,
+                                )
+                        )
+                        for b in range(self.n_bands)
+                ]
+        )
+
+    def compute_masks(self, q):
+        batch, n_bands, n_time, emb_dim = q.shape
+
+        masks = []
+
+        for b, nmlp in enumerate(self.norm_mlp):
+            # print(f"maskestim/{b:02d}")
+            qb = q[:, b, :, :]
+            mb = nmlp(qb)
+            masks.append(mb)
+
+        return masks
+
+
+
+class OverlappingMaskEstimationModule(MaskEstimationModuleBase):
+    def __init__(
+            self,
+            in_channel: int,
+            band_specs: List[Tuple[float, float]],
+            freq_weights: List[torch.Tensor],
+            n_freq: int,
+            emb_dim: int,
+            mlp_dim: int,
+            cond_dim: int = 0,
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs: Dict = None,
+            complex_mask: bool = True,
+            norm_mlp_cls: Type[nn.Module] = NormMLP,
+            norm_mlp_kwargs: Dict = None,
+            use_freq_weights: bool = True,
+    ) -> None:
+        check_nonzero_bandwidth(band_specs)
+        check_no_gap(band_specs)
+
+        # if cond_dim > 0:
+        #     raise NotImplementedError
+
+        super().__init__(
+                band_specs=band_specs,
+                emb_dim=emb_dim + cond_dim,
+                mlp_dim=mlp_dim,
+                in_channel=in_channel,
+                hidden_activation=hidden_activation,
+                hidden_activation_kwargs=hidden_activation_kwargs,
+                complex_mask=complex_mask,
+                norm_mlp_cls=norm_mlp_cls,
+                norm_mlp_kwargs=norm_mlp_kwargs,
+        )
+
+        self.n_freq = n_freq
+        self.band_specs = band_specs
+        self.in_channel = in_channel
+
+        if freq_weights is not None:
+            for i, fw in enumerate(freq_weights):
+                self.register_buffer(f"freq_weights/{i}", fw)
+
+                self.use_freq_weights = use_freq_weights
+        else:
+            self.use_freq_weights = False
+
+        self.cond_dim = cond_dim
+
+    def forward(self, q, cond=None):
+        # q = (batch, n_bands, n_time, emb_dim)
+
+        batch, n_bands, n_time, emb_dim = q.shape
+
+        if cond is not None:
+            print(cond)
+            if cond.ndim == 2:
+                cond = cond[:, None, None, :].expand(-1, n_bands, n_time, -1)
+            elif cond.ndim == 3:
+                assert cond.shape[1] == n_time
+            else:
+                raise ValueError(f"Invalid cond shape: {cond.shape}")
+
+            q = torch.cat([q, cond], dim=-1)
+        elif self.cond_dim > 0:
+            cond = torch.ones(
+                    (batch, n_bands, n_time, self.cond_dim),
+                    device=q.device,
+                    dtype=q.dtype,
+            )
+            q = torch.cat([q, cond], dim=-1)
+        else:
+            pass
+
+        mask_list = self.compute_masks(
+                q
+        )  # [n_bands  * (batch, in_channel, bandwidth, n_time)]
+
+        masks = torch.zeros(
+                (batch, self.in_channel, self.n_freq, n_time),
+                device=q.device,
+                dtype=mask_list[0].dtype,
+        )
+
+        for im, mask in enumerate(mask_list):
+            fstart, fend = self.band_specs[im]
+            if self.use_freq_weights:
+                fw = self.get_buffer(f"freq_weights/{im}")[:, None]
+                mask = mask * fw
+            masks[:, :, fstart:fend, :] += mask
+
+        return masks
+
+
+class MaskEstimationModule(OverlappingMaskEstimationModule):
+    def __init__(
+            self,
+            band_specs: List[Tuple[float, float]],
+            emb_dim: int,
+            mlp_dim: int,
+            in_channel: Optional[int],
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs: Dict = None,
+            complex_mask: bool = True,
+            **kwargs,
+    ) -> None:
+        check_nonzero_bandwidth(band_specs)
+        check_no_gap(band_specs)
+        check_no_overlap(band_specs)
+        super().__init__(
+                in_channel=in_channel,
+                band_specs=band_specs,
+                freq_weights=None,
+                n_freq=None,
+                emb_dim=emb_dim,
+                mlp_dim=mlp_dim,
+                hidden_activation=hidden_activation,
+                hidden_activation_kwargs=hidden_activation_kwargs,
+                complex_mask=complex_mask,
+        )
+
+    def forward(self, q, cond=None):
+        # q = (batch, n_bands, n_time, emb_dim)
+
+        masks = self.compute_masks(
+                q
+        )  # [n_bands  * (batch, in_channel, bandwidth, n_time)]
+
+        # TODO: currently this requires band specs to have no gap and no overlap
+        masks = torch.concat(
+                masks,
+                dim=2
+        )  # (batch, in_channel, n_freq, n_time)
+
+        return masks
diff --git a/freevideo_engine/stems/bandit/spectral.py b/freevideo_engine/stems/bandit/spectral.py
new file mode 100644
index 00000000..ae0700c5
--- /dev/null
+++ b/freevideo_engine/stems/bandit/spectral.py
@@ -0,0 +1,60 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+from typing import Dict, Optional
+
+import torch
+import torchaudio as ta
+from torch import nn
+
+
+class _SpectralComponent(nn.Module):
+    def __init__(
+            self,
+            n_fft: int = 2048,
+            win_length: Optional[int] = 2048,
+            hop_length: int = 512,
+            window_fn: str = "hann_window",
+            wkwargs: Optional[Dict] = None,
+            power: Optional[int] = None,
+            center: bool = True,
+            normalized: bool = True,
+            pad_mode: str = "constant",
+            onesided: bool = True,
+            **kwargs,
+    ) -> None:
+        super().__init__()
+
+        assert power is None
+
+        window_fn = torch.__dict__[window_fn]
+
+        self.stft = (
+                ta.transforms.Spectrogram(
+                        n_fft=n_fft,
+                        win_length=win_length,
+                        hop_length=hop_length,
+                        pad_mode=pad_mode,
+                        pad=0,
+                        window_fn=window_fn,
+                        wkwargs=wkwargs,
+                        power=power,
+                        normalized=normalized,
+                        center=center,
+                        onesided=onesided,
+                )
+        )
+
+        self.istft = (
+                ta.transforms.InverseSpectrogram(
+                        n_fft=n_fft,
+                        win_length=win_length,
+                        hop_length=hop_length,
+                        pad_mode=pad_mode,
+                        pad=0,
+                        window_fn=window_fn,
+                        wkwargs=wkwargs,
+                        normalized=normalized,
+                        center=center,
+                        onesided=onesided,
+                )
+        )
diff --git a/freevideo_engine/stems/bandit/tfmodel.py b/freevideo_engine/stems/bandit/tfmodel.py
new file mode 100644
index 00000000..ae709b82
--- /dev/null
+++ b/freevideo_engine/stems/bandit/tfmodel.py
@@ -0,0 +1,177 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+import warnings
+
+import torch
+from torch import nn
+from torch.nn.modules import rnn
+
+import torch.backends.cuda
+
+
+class TimeFrequencyModellingModule(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+
+
+class ResidualRNN(nn.Module):
+    def __init__(
+            self,
+            emb_dim: int,
+            rnn_dim: int,
+            bidirectional: bool = True,
+            rnn_type: str = "LSTM",
+            use_batch_trick: bool = True,
+            use_layer_norm: bool = True,
+    ) -> None:
+        # n_group is the size of the 2nd dim
+        super().__init__()
+
+        self.use_layer_norm = use_layer_norm
+        if use_layer_norm:
+            self.norm = nn.LayerNorm(emb_dim)
+        else:
+            self.norm = nn.GroupNorm(num_groups=emb_dim, num_channels=emb_dim)
+
+        self.rnn = rnn.__dict__[rnn_type](
+                input_size=emb_dim,
+                hidden_size=rnn_dim,
+                num_layers=1,
+                batch_first=True,
+                bidirectional=bidirectional,
+        )
+
+        self.fc = nn.Linear(
+                in_features=rnn_dim * (2 if bidirectional else 1),
+                out_features=emb_dim
+        )
+
+        self.use_batch_trick = use_batch_trick
+        if not self.use_batch_trick:
+            warnings.warn("NOT USING BATCH TRICK IS EXTREMELY SLOW!!")
+
+    def forward(self, z):
+        # z = (batch, n_uncrossed, n_across, emb_dim)
+
+        z0 = torch.clone(z)
+
+        # print(z.device)
+
+        if self.use_layer_norm:
+            z = self.norm(z)  # (batch, n_uncrossed, n_across, emb_dim)
+        else:
+            z = torch.permute(
+                    z, (0, 3, 1, 2)
+            )  # (batch, emb_dim, n_uncrossed, n_across)
+
+            z = self.norm(z)  # (batch, emb_dim, n_uncrossed, n_across)
+
+            z = torch.permute(
+                    z, (0, 2, 3, 1)
+            )  # (batch, n_uncrossed, n_across, emb_dim)
+
+        batch, n_uncrossed, n_across, emb_dim = z.shape
+
+        if self.use_batch_trick:
+            z = torch.reshape(z, (batch * n_uncrossed, n_across, emb_dim))
+
+            z = self.rnn(z.contiguous())[0]  # (batch * n_uncrossed, n_across, dir_rnn_dim)
+
+            z = torch.reshape(z, (batch, n_uncrossed, n_across, -1))
+            # (batch, n_uncrossed, n_across, dir_rnn_dim)
+        else:
+            # Note: this is EXTREMELY SLOW
+            zlist = []
+            for i in range(n_uncrossed):
+                zi = self.rnn(z[:, i, :, :])[0]  # (batch, n_across, emb_dim)
+                zlist.append(zi)
+
+            z = torch.stack(
+                    zlist,
+                    dim=1
+            )  # (batch, n_uncrossed, n_across, dir_rnn_dim)
+
+        z = self.fc(z)  # (batch, n_uncrossed, n_across, emb_dim)
+
+        z = z + z0
+
+        return z
+
+
+class SeqBandModellingModule(TimeFrequencyModellingModule):
+    def __init__(
+            self,
+            n_modules: int = 12,
+            emb_dim: int = 128,
+            rnn_dim: int = 256,
+            bidirectional: bool = True,
+            rnn_type: str = "LSTM",
+            parallel_mode=False,
+    ) -> None:
+        super().__init__()
+        self.seqband = nn.ModuleList([])
+
+        if parallel_mode:
+            for _ in range(n_modules):
+                self.seqband.append(
+                        nn.ModuleList(
+                                [ResidualRNN(
+                                        emb_dim=emb_dim,
+                                        rnn_dim=rnn_dim,
+                                        bidirectional=bidirectional,
+                                        rnn_type=rnn_type,
+                                ),
+                                        ResidualRNN(
+                                                emb_dim=emb_dim,
+                                                rnn_dim=rnn_dim,
+                                                bidirectional=bidirectional,
+                                                rnn_type=rnn_type,
+                                        )]
+                        )
+                )
+        else:
+
+            for _ in range(2 * n_modules):
+                self.seqband.append(
+                        ResidualRNN(
+                                emb_dim=emb_dim,
+                                rnn_dim=rnn_dim,
+                                bidirectional=bidirectional,
+                                rnn_type=rnn_type,
+                        )
+                )
+
+        self.parallel_mode = parallel_mode
+
+    def forward(self, z):
+        # z = (batch, n_bands, n_time, emb_dim)
+
+        if self.parallel_mode:
+            for sbm_pair in self.seqband:
+                # z: (batch, n_bands, n_time, emb_dim)
+                sbm_t, sbm_f = sbm_pair[0], sbm_pair[1]
+                zt = sbm_t(z) # (batch, n_bands, n_time, emb_dim)
+                zf = sbm_f(z.transpose(1, 2)) # (batch, n_time, n_bands, emb_dim)
+                z = zt + zf.transpose(1, 2)
+        else:
+            for sbm in self.seqband:
+                z = sbm(z)
+                z = z.transpose(1, 2)
+
+                # (batch, n_bands, n_time, emb_dim)
+                #   --> (batch, n_time, n_bands, emb_dim)
+                # OR
+                # (batch, n_time, n_bands, emb_dim)
+                #   --> (batch, n_bands, n_time, emb_dim)
+
+        q = z
+        return q  # (batch, n_bands, n_time, emb_dim)
+
+
+
+
+
+
+
+
+
diff --git a/freevideo_engine/stems/bandit/utils.py b/freevideo_engine/stems/bandit/utils.py
new file mode 100644
index 00000000..c68c7b0f
--- /dev/null
+++ b/freevideo_engine/stems/bandit/utils.py
@@ -0,0 +1,260 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+import os
+from abc import abstractmethod
+from typing import Callable
+
+import numpy as np
+import torch
+
+
+def hz_to_midi(frequency):
+    return 12 * (np.log2(np.asanyarray(frequency)) - np.log2(440.0)) + 69
+
+
+def midi_to_hz(notes):
+    return 440.0 * (2.0 ** ((np.asanyarray(notes) - 69.0) / 12.0))
+
+
+def band_widths_from_specs(band_specs):
+    return [e - i for i, e in band_specs]
+
+
+def check_nonzero_bandwidth(band_specs):
+    # pprint(band_specs)
+    for fstart, fend in band_specs:
+        if fend - fstart <= 0:
+            raise ValueError("Bands cannot be zero-width")
+
+
+def check_no_overlap(band_specs):
+    fend_prev = -1
+    for fstart_curr, fend_curr in band_specs:
+        if fstart_curr <= fend_prev:
+            raise ValueError("Bands cannot overlap")
+
+
+def check_no_gap(band_specs):
+    fstart, _ = band_specs[0]
+    assert fstart == 0
+
+    fend_prev = -1
+    for fstart_curr, fend_curr in band_specs:
+        if fstart_curr - fend_prev > 1:
+            raise ValueError("Bands cannot leave gap")
+        fend_prev = fend_curr
+
+
+class BandsplitSpecification:
+    def __init__(self, nfft: int, fs: int) -> None:
+        self.fs = fs
+        self.nfft = nfft
+        self.nyquist = fs / 2
+        self.max_index = nfft // 2 + 1
+
+        self.split500 = self.hertz_to_index(500)
+        self.split1k = self.hertz_to_index(1000)
+        self.split2k = self.hertz_to_index(2000)
+        self.split4k = self.hertz_to_index(4000)
+        self.split8k = self.hertz_to_index(8000)
+        self.split16k = self.hertz_to_index(16000)
+        self.split20k = self.hertz_to_index(20000)
+
+        self.above20k = [(self.split20k, self.max_index)]
+        self.above16k = [(self.split16k, self.split20k)] + self.above20k
+
+    def index_to_hertz(self, index: int):
+        return index * self.fs / self.nfft
+
+    def hertz_to_index(self, hz: float, round: bool = True):
+        index = hz * self.nfft / self.fs
+
+        if round:
+            index = int(np.round(index))
+
+        return index
+
+    def get_band_specs_with_bandwidth(
+            self,
+            start_index,
+            end_index,
+            bandwidth_hz
+            ):
+        band_specs = []
+        lower = start_index
+
+        while lower < end_index:
+            upper = int(np.floor(lower + self.hertz_to_index(bandwidth_hz)))
+            upper = min(upper, end_index)
+
+            band_specs.append((lower, upper))
+            lower = upper
+
+        return band_specs
+
+    @abstractmethod
+    def get_band_specs(self):
+        raise NotImplementedError
+
+
+
+
+
+
+
+
+
+
+
+
+class PerceptualBandsplitSpecification(BandsplitSpecification):
+    def __init__(
+            self,
+            nfft: int,
+            fs: int,
+            fbank_fn: Callable[[int, int, float, float, int], torch.Tensor],
+            n_bands: int,
+            f_min: float = 0.0,
+            f_max: float = None
+    ) -> None:
+        super().__init__(nfft=nfft, fs=fs)
+        self.n_bands = n_bands
+        if f_max is None:
+            f_max = fs / 2
+
+        self.filterbank = fbank_fn(
+                n_bands, fs, f_min, f_max, self.max_index
+        )
+
+        weight_per_bin = torch.sum(
+            self.filterbank,
+            dim=0,
+            keepdim=True
+            )  # (1, n_freqs)
+        normalized_mel_fb = self.filterbank / weight_per_bin  # (n_mels, n_freqs)
+
+        freq_weights = []
+        band_specs = []
+        for i in range(self.n_bands):
+            active_bins = torch.nonzero(self.filterbank[i, :]).squeeze().tolist()
+            if isinstance(active_bins, int):
+                active_bins = (active_bins, active_bins)
+            if len(active_bins) == 0:
+                continue
+            start_index = active_bins[0]
+            end_index = active_bins[-1] + 1
+            band_specs.append((start_index, end_index))
+            freq_weights.append(normalized_mel_fb[i, start_index:end_index])
+
+        self.freq_weights = freq_weights
+        self.band_specs = band_specs
+
+    def get_band_specs(self):
+        return self.band_specs
+
+    def get_freq_weights(self):
+        return self.freq_weights
+
+    def save_to_file(self, dir_path: str) -> None:
+
+        os.makedirs(dir_path, exist_ok=True)
+
+        import pickle
+
+        with open(os.path.join(dir_path, "mel_bandsplit_spec.pkl"), "wb") as f:
+            pickle.dump(
+                    {
+                            "band_specs": self.band_specs,
+                            "freq_weights": self.freq_weights,
+                            "filterbank": self.filterbank,
+                    },
+                    f,
+            )
+
+
+
+
+def musical_filterbank(n_bands, fs, f_min, f_max, n_freqs,
+                       scale="constant"):
+
+    nfft = 2 * (n_freqs - 1)
+    df = fs / nfft
+    # init freqs
+    f_max = f_max or fs / 2
+    f_min = f_min or 0
+    f_min = fs / nfft
+
+    n_octaves = np.log2(f_max / f_min)
+    n_octaves_per_band = n_octaves / n_bands
+    bandwidth_mult = np.power(2.0, n_octaves_per_band)
+
+    low_midi = max(0, hz_to_midi(f_min))
+    high_midi = hz_to_midi(f_max)
+    midi_points = np.linspace(low_midi, high_midi, n_bands)
+    hz_pts = midi_to_hz(midi_points)
+
+    low_pts = hz_pts / bandwidth_mult
+    high_pts = hz_pts * bandwidth_mult
+
+    low_bins = np.floor(low_pts / df).astype(int)
+    high_bins = np.ceil(high_pts / df).astype(int)
+
+    fb = np.zeros((n_bands, n_freqs))
+
+    for i in range(n_bands):
+        fb[i, low_bins[i]:high_bins[i]+1] = 1.0
+
+    fb[0, :low_bins[0]] = 1.0
+    fb[-1, high_bins[-1]+1:] = 1.0
+
+    return torch.as_tensor(fb)
+
+class MusicalBandsplitSpecification(PerceptualBandsplitSpecification):
+    def __init__(
+            self,
+            nfft: int,
+            fs: int,
+            n_bands: int,
+            f_min: float = 0.0,
+            f_max: float = None
+    ) -> None:
+        super().__init__(fbank_fn=musical_filterbank, nfft=nfft, fs=fs, n_bands=n_bands, f_min=f_min, f_max=f_max)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+if __name__ == "__main__":
+    import pandas as pd
+
+    band_defs = []
+
+    for bands in [VocalBandsplitSpecification]:  
+        band_name = bands.__name__.replace("BandsplitSpecification", "")
+
+        mbs = bands(nfft=2048, fs=44100).get_band_specs()
+
+        for i, (f_min, f_max) in enumerate(mbs):
+            band_defs.append({
+                "band": band_name,
+                "band_index": i,
+                "f_min": f_min,
+                "f_max": f_max
+            })
+
+    df = pd.DataFrame(band_defs)
+    df.to_csv("vox7bands.csv", index=False)
\ No newline at end of file
diff --git a/freevideo_engine/stems/bandit/wrapper.py b/freevideo_engine/stems/bandit/wrapper.py
new file mode 100644
index 00000000..2f5e871d
--- /dev/null
+++ b/freevideo_engine/stems/bandit/wrapper.py
@@ -0,0 +1,190 @@
+# Adapted from Bandit (https://github.com/kwatcharasupat/source-separation), Copyright (c) the Bandit authors,
+# Apache-2.0 (freevideo_engine/licenses/Bandit-Apache-2.0.txt). Modified: reduced to the inference subset.
+from typing import Dict, List, Optional, Tuple, Union
+
+import torch
+from torch import nn
+
+from .core import MultiSourceMultiMaskBandSplitCoreRNN
+from .spectral import _SpectralComponent
+from .utils import MusicalBandsplitSpecification
+
+
+def get_band_specs(band_specs, n_fft, fs, n_bands=None):
+    if "musical" not in band_specs or n_bands is None:
+        raise NameError(band_specs)
+    specs = MusicalBandsplitSpecification(nfft=n_fft, fs=fs, n_bands=n_bands)
+    return specs.get_band_specs(), specs.get_freq_weights(), True
+
+
+class BandSplitWrapperBase(nn.Module):
+    bsrnn: nn.Module
+    
+    def __init__(self, **kwargs):
+        super().__init__()
+
+
+
+
+class MultiMaskMultiSourceBandSplitBase(
+        BandSplitWrapperBase,
+        _SpectralComponent
+):
+    def __init__(
+            self,
+            stems: List[str],
+            band_specs: Union[str, List[Tuple[float, float]]],
+            fs: int = 44100,
+            n_fft: int = 2048,
+            win_length: Optional[int] = 2048,
+            hop_length: int = 512,
+            window_fn: str = "hann_window",
+            wkwargs: Optional[Dict] = None,
+            power: Optional[int] = None,
+            center: bool = True,
+            normalized: bool = True,
+            pad_mode: str = "constant",
+            onesided: bool = True,
+            n_bands: int = None,
+    ) -> None:
+        super().__init__(
+                n_fft=n_fft,
+                win_length=win_length,
+                hop_length=hop_length,
+                window_fn=window_fn,
+                wkwargs=wkwargs,
+                power=power,
+                center=center,
+                normalized=normalized,
+                pad_mode=pad_mode,
+                onesided=onesided,
+        )
+
+        if isinstance(band_specs, str):
+            self.band_specs, self.freq_weights, self.overlapping_band = get_band_specs(
+                band_specs,
+                n_fft,
+                fs,
+                n_bands
+                )
+
+        self.stems = stems
+
+    def forward(self, batch):
+        # with torch.no_grad():
+        audio = batch["audio"]
+        cond = batch.get("condition", None)
+        with torch.no_grad():
+            batch["spectrogram"] = {stem: self.stft(audio[stem]) for stem in
+                                    audio}
+
+        X = batch["spectrogram"]["mixture"]
+        length = batch["audio"]["mixture"].shape[-1]
+
+        output = self.bsrnn(X, cond=cond)
+        output["audio"] = {}
+
+        for stem, S in output["spectrogram"].items():
+            s = self.istft(S, length)
+            output["audio"][stem] = s
+
+        return batch, output
+
+
+
+
+
+
+class MultiMaskMultiSourceBandSplitRNN(MultiMaskMultiSourceBandSplitBase):
+    def __init__(
+            self,
+            in_channel: int,
+            stems: List[str],
+            band_specs: Union[str, List[Tuple[float, float]]],
+            fs: int = 44100,
+            require_no_overlap: bool = False,
+            require_no_gap: bool = True,
+            normalize_channel_independently: bool = False,
+            treat_channel_as_feature: bool = True,
+            n_sqm_modules: int = 12,
+            emb_dim: int = 128,
+            rnn_dim: int = 256,
+            cond_dim: int = 0,
+            bidirectional: bool = True,
+            rnn_type: str = "LSTM",
+            mlp_dim: int = 512,
+            hidden_activation: str = "Tanh",
+            hidden_activation_kwargs: Optional[Dict] = None,
+            complex_mask: bool = True,
+            n_fft: int = 2048,
+            win_length: Optional[int] = 2048,
+            hop_length: int = 512,
+            window_fn: str = "hann_window",
+            wkwargs: Optional[Dict] = None,
+            power: Optional[int] = None,
+            center: bool = True,
+            normalized: bool = True,
+            pad_mode: str = "constant",
+            onesided: bool = True,
+            n_bands: int = None,
+            use_freq_weights: bool = True,
+            normalize_input: bool = False,
+            mult_add_mask: bool = False,
+            freeze_encoder: bool = False,
+    ) -> None:
+        super().__init__(
+                stems=stems,
+                band_specs=band_specs,
+                fs=fs,
+                n_fft=n_fft,
+                win_length=win_length,
+                hop_length=hop_length,
+                window_fn=window_fn,
+                wkwargs=wkwargs,
+                power=power,
+                center=center,
+                normalized=normalized,
+                pad_mode=pad_mode,
+                onesided=onesided,
+                n_bands=n_bands,
+        )
+
+        self.bsrnn = MultiSourceMultiMaskBandSplitCoreRNN(
+                stems=stems,
+                band_specs=self.band_specs,
+                in_channel=in_channel,
+                require_no_overlap=require_no_overlap,
+                require_no_gap=require_no_gap,
+                normalize_channel_independently=normalize_channel_independently,
+                treat_channel_as_feature=treat_channel_as_feature,
+                n_sqm_modules=n_sqm_modules,
+                emb_dim=emb_dim,
+                rnn_dim=rnn_dim,
+                bidirectional=bidirectional,
+                rnn_type=rnn_type,
+                mlp_dim=mlp_dim,
+                cond_dim=cond_dim,
+                hidden_activation=hidden_activation,
+                hidden_activation_kwargs=hidden_activation_kwargs,
+                complex_mask=complex_mask,
+                overlapping_band=self.overlapping_band,
+                freq_weights=self.freq_weights,
+                n_freq=n_fft // 2 + 1,
+                use_freq_weights=use_freq_weights,
+                mult_add_mask=mult_add_mask
+        )
+
+        self.normalize_input = normalize_input
+        self.cond_dim = cond_dim
+
+        if freeze_encoder:
+            for param in self.bsrnn.band_split.parameters():
+                param.requires_grad = False
+
+            for param in self.bsrnn.tf_model.parameters():
+                param.requires_grad = False
+
+
+
+
+
diff --git a/freevideo_engine/stems/separate.py b/freevideo_engine/stems/separate.py
new file mode 100644
index 00000000..2059ab9f
--- /dev/null
+++ b/freevideo_engine/stems/separate.py
@@ -0,0 +1,200 @@
+"""Split a soundtrack into dialogue, music, and ambience and effects.
+
+The model is a band-split recurrent network (Bandit, cocktail-party version) that works on 44.1 kHz mono
+signals. A track is cut into overlapping 6 s chunks (3 s hop, Hann window), a few chunks go through the
+model at a time, and the windowed outputs are added back, so the peak GPU memory does not depend on the
+length of the track and every output has exactly the length of the input.
+"""
+from fractions import Fraction
+import logging
+import os
+from pathlib import Path
+import wave
+
+import numpy as np
+
+SAMPLE_RATE = 44100
+CHUNK_SECONDS = 6.0
+HOP_SECONDS = 3.0
+BATCH = 4
+MIX_NAME = 'mix.wav'
+
+# Model output name -> track name. The order is the order of the sub-tracks in the editor.
+STEMS = (('speech', 'dialogue'), ('music', 'music'), ('effects', 'ambience'))
+MODEL_KWARGS = dict(
+    in_channel=1, stems=[name for name, _ in STEMS], band_specs='musical', n_bands=64, fs=SAMPLE_RATE,
+    require_no_overlap=False, require_no_gap=True, normalize_channel_independently=False,
+    treat_channel_as_feature=True, n_sqm_modules=8, emb_dim=128, rnn_dim=256, bidirectional=True,
+    rnn_type='GRU', mlp_dim=512, hidden_activation='Tanh', complex_mask=True)
+
+
+class SeparationError(Exception):
+    pass
+
+
+def load_model(weights, device='cuda'):
+    """The network with its weights; weights is a plain state-dict file (loaded without unpickling objects)."""
+    import torch
+    from .bandit.wrapper import MultiMaskMultiSourceBandSplitRNN
+    model = MultiMaskMultiSourceBandSplitRNN(**MODEL_KWARGS)
+    state = torch.load(weights, map_location='cpu', weights_only=True)
+    model.load_state_dict(state)
+    return model.to(device).eval()
+
+
+def model_function(model, device):
+    """Chunks [n, 1, samples] -> {model stem: [n, 1, samples]}, run without gradients."""
+    import torch
+
+    def run(chunks):
+        with torch.inference_mode():
+            _, output = model({'audio': {'mixture': chunks.to(device)}})
+        return {name: output['audio'][name].float().cpu() for name, _ in STEMS}
+    return run
+
+
+def separate_array(function, audio, *, chunk=None, hop=None, batch=BATCH, progress=lambda fraction: None):
+    """audio: float tensor [channels, samples]; function maps chunks [n, 1, chunk] to {stem: [n, 1, chunk]}.
+
+    Returns {stem: tensor [channels, samples]} with the length of the input. Every channel is separated on its own."""
+    import torch
+    chunk = chunk or int(CHUNK_SECONDS * SAMPLE_RATE)
+    hop = hop or int(HOP_SECONDS * SAMPLE_RATE)
+    channels, length = audio.shape
+    if length == 0:
+        raise SeparationError('empty')
+    if chunk != 2 * hop:
+        raise SeparationError('chunk must be twice the hop')
+    # Half a chunk of mirrored context on both sides keeps the edges as well covered as the middle.
+    edge = chunk - hop
+    padded_length = max(length + 2 * edge, chunk)
+    count = -(-(padded_length - chunk) // hop) + 1
+    total = (count - 1) * hop + chunk
+    padded = torch.zeros(channels, total)
+    padded[:, edge:edge + length] = audio
+    for left in range(1, edge + 1):  # mirror as far as the signal reaches; the rest stays silent
+        if left < length:
+            padded[:, edge - left] = audio[:, left]
+            padded[:, edge + length - 1 + left] = audio[:, length - 1 - left]
+    window = torch.hann_window(chunk, periodic=True)
+    starts = [index * hop for index in range(count)]
+    outputs = {name: torch.zeros(channels, total) for name, _ in STEMS}
+    jobs = [(channel, start) for channel in range(channels) for start in starts]
+    for first in range(0, len(jobs), batch):
+        part = jobs[first:first + batch]
+        pieces = torch.stack([padded[channel, start:start + chunk] for channel, start in part])[:, None, :]
+        if torch.any(pieces != 0):
+            result = function(pieces)
+            for name, _ in STEMS:
+                for row, (channel, start) in enumerate(part):
+                    outputs[name][channel, start:start + chunk] += result[name][row, 0] * window
+        progress(min(1., (first + len(part)) / len(jobs)))
+    return {name: value[:, edge:edge + length].contiguous() for name, value in outputs.items()}
+
+
+def read_audio(path):
+    """Decode any audio or video file to float32 [2, samples] at 44.1 kHz; returns (audio, seconds)."""
+    import av
+    chunks = []
+    with av.open(str(path)) as container:
+        if not container.streams.audio:
+            raise SeparationError('no_audio')
+        resampler = av.AudioResampler(format='fltp', layout='stereo', rate=SAMPLE_RATE)
+        for frame in container.decode(audio=0):
+            for out in resampler.resample(frame):
+                chunks.append(out.to_ndarray())
+        for out in resampler.resample(None) or ():
+            chunks.append(out.to_ndarray())
+    if not chunks:
+        raise SeparationError('no_audio')
+    audio = np.concatenate(chunks, axis=1).astype(np.float32)
+    return audio, audio.shape[1] / SAMPLE_RATE
+
+
+def write_wav(path, audio):
+    """Atomically write float [2, samples] as 16-bit PCM at 44.1 kHz."""
+    path = Path(path)
+    audio = np.asarray(audio)
+    pcm = np.rint(np.clip(audio.T, -1, 1) * 32767).astype('<i2')
+    temporary = path.with_name('.' + path.name + '.partial')
+    try:
+        with wave.open(str(temporary), 'wb') as output:
+            output.setnchannels(audio.shape[0])
+            output.setsampwidth(2)
+            output.setframerate(SAMPLE_RATE)
+            output.writeframes(pcm.tobytes())
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def write_mp4(path, audio, bit_rate=192_000):
+    """AAC in an audio-only MP4, the container the timeline takes for generated media; replaced atomically."""
+    import av
+    path = Path(path)
+    audio = np.asarray(audio, np.float32)
+    partial = path.with_name('.' + path.name + '.partial')
+    try:
+        with av.open(str(partial), 'w', format='mp4', options={'movflags': 'faststart'}) as writer:
+            stream = writer.add_stream('aac', rate=SAMPLE_RATE, layout='stereo')
+            stream.codec_context.bit_rate = bit_rate
+            step = 1024 * 32
+            for offset in range(0, audio.shape[1], step):
+                frame = av.AudioFrame.from_ndarray(np.ascontiguousarray(audio[:, offset:offset + step]),
+                                                   format='fltp', layout='stereo')
+                frame.sample_rate, frame.pts, frame.time_base = SAMPLE_RATE, offset, Fraction(1, SAMPLE_RATE)
+                for packet in stream.encode(frame):
+                    writer.mux(packet)
+            for packet in stream.encode():
+                writer.mux(packet)
+        os.replace(partial, path)
+    finally:
+        partial.unlink(missing_ok=True)
+
+
+def separate_file(source, out_dir, weights, *, device='cuda', progress=lambda fraction: None):
+    """Write <out_dir>/dialogue, music and ambience as .wav (export) and .mp4 (timeline), plus the original mix as
+    mix.wav; returns {track: wav path} and the log numbers."""
+    import time
+    import torch
+    began = time.monotonic()
+    audio, seconds = read_audio(source)
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    model = load_model(weights, device)
+    if device == 'cuda':
+        torch.cuda.reset_peak_memory_stats()
+    stems = separate_array(model_function(model, device), torch.from_numpy(audio), progress=progress)
+    peak = torch.cuda.max_memory_allocated() / 2 ** 30 if device == 'cuda' else None
+    write_wav(out_dir / MIX_NAME, audio)  # the original mix, exported next to the separated tracks
+    paths = {}
+    for name, track in STEMS:
+        paths[track] = out_dir / (track + '.wav')
+        write_wav(paths[track], stems[name].numpy())
+        write_mp4(paths[track].with_suffix('.mp4'), stems[name].numpy())
+    numbers = {'seconds': round(seconds, 3), 'elapsed': round(time.monotonic() - began, 2),
+               'peak_gib': None if peak is None else round(peak, 2)}
+    logging.info('[FreeVideo] Separated %.1f s of sound in %.1f s, GPU peak %s GiB', seconds, numbers['elapsed'],
+                 numbers['peak_gib'])
+    return paths, numbers
+
+
+def export_tracks(source_dir, destination):
+    """Copy the separated tracks and the original mix (wav) of one separation into destination; returns the names.
+
+    Nothing is written unless all four files exist, and existing files of the same names are not overwritten."""
+    import shutil
+    source_dir, destination = Path(source_dir), Path(destination)
+    names = [track + '.wav' for _, track in STEMS] + [MIX_NAME]
+    missing = [name for name in names if not (source_dir / name).is_file()]
+    if missing:
+        raise SeparationError('missing: ' + ', '.join(missing))
+    destination.mkdir(parents=True, exist_ok=True)
+    clash = [name for name in names if (destination / name).exists()]
+    if clash:
+        raise SeparationError('exists: ' + ', '.join(clash))
+    for name in names:
+        shutil.copyfile(source_dir / name, destination / (name + '.partial'))
+    for name in names:
+        os.replace(destination / (name + '.partial'), destination / name)
+    return names
diff --git a/freevideo_engine/stems/service.py b/freevideo_engine/stems/service.py
new file mode 100644
index 00000000..0c4989bd
--- /dev/null
+++ b/freevideo_engine/stems/service.py
@@ -0,0 +1,176 @@
+"""Audio separation for a clip: dialogue, music and ambience written by a one-shot worker under engine.lock.
+
+The weights are the image pack's stems group, downloaded on first use. The worker takes the GPU the way
+music does and stops when a video starts (a video is never kept waiting); the caller waits and asks again.
+The feature is offered only with an NVIDIA GPU of at least MIN_VRAM_GIB and never on macOS.
+"""
+import logging
+from pathlib import Path
+import platform
+import subprocess
+import tempfile
+import time
+
+from ..music.service import Preempted, _Active, _result, _yield_gpu, environment
+
+# An 8 GB card reports about 7.996 GiB, so the bar sits just under 8.
+MIN_VRAM_GIB = 7.5
+WORKER_SECONDS = 1800
+POLL_SECONDS = .2
+WEIGHTS = 'stems/bandit_plus_cocktail.pt'
+
+
+class StemsError(Exception):
+    def __init__(self, code, reason=None):
+        super().__init__(code)
+        self.code, self.reason = code, reason
+
+
+ACTIVE = _Active()
+
+
+def stop_for_generation(server=None):
+    """Called as a video starts: a separation that is starting or running stops, and engine.lock is free on return."""
+    from .. import processes
+    with ACTIVE.lock:
+        if ACTIVE.idle.is_set():
+            return
+        ACTIVE.preempted = True
+        process = ACTIVE.process
+    if process is not None:
+        processes.stop(process, grace=5)
+    ACTIVE.idle.wait(30)
+
+
+def gpu_total_gib(uuid=None):
+    """Physical memory in GiB of the GPU FreeVideo uses (the first one when its UUID is unknown), or None when unreadable.
+
+    A reading is kept for the session; a failed one is tried again after RETRY_SECONDS, and waits at most 3 s."""
+    key = str(uuid or 0)
+    kept = _TOTAL.get(key)
+    if kept is not None and (kept[0] is not None or time.monotonic() < kept[1]):
+        return kept[0]
+    try:
+        out = subprocess.run(['nvidia-smi', '--query-gpu=memory.total', '--format=csv,noheader,nounits', '-i', key],
+                             capture_output=True, text=True, timeout=3, check=True).stdout
+        value = float(out.split()[0]) / 1024
+    except (OSError, ValueError, IndexError, subprocess.SubprocessError):
+        value = None
+    _TOTAL[key] = (value, time.monotonic() + RETRY_SECONDS)
+    return value
+
+
+RETRY_SECONDS = 30
+_TOTAL = {}
+
+
+def supported(vram_gib, system=None, total=None, uuid=None):
+    """Whether the entry is offered: CUDA only, so not on macOS, and enough video memory.
+
+    vram_gib is the limit a user may have set (normally None); the card's own size applies as well."""
+    sizes = [v for v in (vram_gib, total if total is not None else gpu_total_gib(uuid)) if v is not None]
+    return (system or platform.system()) != 'Darwin' and bool(sizes) and min(sizes) >= MIN_VRAM_GIB
+
+
+def ready(model_root):
+    from ..image_gen import image_pack
+    return image_pack.ready(model_root, group='stems')
+
+
+def install(model_root, engine_root, progress, cancelled):
+    from ..image_gen import image_pack
+
+    def check():
+        if cancelled():
+            raise InterruptedError('cancelled')
+
+    def moved(value):
+        if value.get('phase') == 'download' and value.get('total'):
+            progress(min(1., value['done'] / value['total']))
+    try:
+        image_pack.install(model_root, moved, check, engine_root=engine_root, group='stems')
+    except image_pack.PackError as error:
+        raise StemsError('stems_download_failed', error.reason) from None
+
+
+def separate(source, out_dir, *, server=None, cancelled=lambda: False, phase=lambda name, fraction=None: None):
+    """Write dialogue.wav, music.wav and ambience.wav into out_dir; returns the worker's result.
+
+    Raises Preempted when a video started, InterruptedError when cancelled, StemsError otherwise."""
+    from ..comfy_bridge import installation
+    root, machine = installation()
+    if not ready(machine['model_root']):
+        phase('downloading', 0.)
+        install(machine['model_root'], root, lambda fraction: phase('downloading', fraction), cancelled)
+    if cancelled():
+        raise InterruptedError('cancelled')
+    phase('separating')
+    with ACTIVE.lock:
+        ACTIVE.preempted = False
+        ACTIVE.idle.clear()
+    try:
+        return _run(source, out_dir, server, cancelled, root, machine)
+    except BlockingIOError:
+        raise Preempted() from None
+    finally:
+        with ACTIVE.lock:
+            ACTIVE.process = None
+            ACTIVE.idle.set()
+
+
+def _run(source, out_dir, server, cancelled, root, machine):
+    from ..image_gen import image_pack
+    from ..locking import runtime_lock
+    from .. import processes, resident_process
+    _yield_gpu(server)
+    with runtime_lock(Path(root) / 'engine.lock', inherit=False, wait_seconds=10) as descriptor:
+        env = environment(root)
+        owner = resident_process.OWNER
+        if owner.process is not None and owner.process.poll() is None and owner.endpoint:
+            env[resident_process.ENV] = str(owner.endpoint)
+            try:
+                resident_process.release_idle_cache(env, descriptor)
+                owner.record(action='released', reason='stems_model')
+            except resident_process.SessionRestarted:
+                pass
+            env.pop(resident_process.ENV, None)
+        command = processes.module_command(
+            'freevideo_engine.stems.worker', '--weights', image_pack.base(machine['model_root']) / WEIGHTS,
+            '--source', source, '--out', out_dir, '--device', machine.get('device_backend', 'cuda'))
+        command[0] = machine['comfy_python']
+        env['FREEVIDEO_RUNTIME_LOCK_FD'] = str(descriptor)
+        with tempfile.TemporaryFile() as output, tempfile.TemporaryFile() as errors:
+            with ACTIVE.lock:
+                if ACTIVE.preempted:
+                    raise Preempted()
+                process = processes.popen(command, env=env, stdin=subprocess.DEVNULL, stdout=output, stderr=errors,
+                                          pass_fds=(descriptor,), supervise=True, start_new_session=True)
+                ACTIVE.process = process
+            began, timed_out = time.monotonic(), False
+            try:
+                while process.poll() is None:
+                    timed_out = time.monotonic() - began > WORKER_SECONDS
+                    if cancelled() or timed_out:
+                        break
+                    time.sleep(POLL_SECONDS)
+            finally:
+                if process.poll() is None:
+                    processes.stop(process, grace=5)
+                process.wait()
+                with ACTIVE.lock:
+                    ACTIVE.process = None
+                    preempted = ACTIVE.preempted
+            if preempted:
+                raise Preempted()
+            if cancelled():
+                raise InterruptedError('cancelled')
+            value = _result(output)
+            if not value.get('ok'):
+                errors.seek(0, 2)
+                errors.seek(max(0, errors.tell() - 4000))
+                logging.warning('[FreeVideo] Separation worker failed (exit %s, %s): %s', process.returncode,
+                                value.get('error') or 'no result', errors.read().decode('utf-8', 'replace'))
+                code = value.get('error')
+                raise StemsError('out_of_memory' if code == 'out_of_memory' else code if code == 'no_audio'
+                                 else 'stems_failed', code if isinstance(code, str) else 'timeout' if timed_out else 'worker_exit')
+            return value
diff --git a/freevideo_engine/stems/worker.py b/freevideo_engine/stems/worker.py
new file mode 100644
index 00000000..8a964ca2
--- /dev/null
+++ b/freevideo_engine/stems/worker.py
@@ -0,0 +1,40 @@
+"""Run one audio separation in an isolated process and emit a final machine-readable JSON line."""
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+def main(argv=None):
+    code = 'bad_request'
+    try:
+        parser = argparse.ArgumentParser(description=__doc__)
+        parser.add_argument('--weights', required=True)
+        parser.add_argument('--source', required=True)
+        parser.add_argument('--out', required=True)
+        parser.add_argument('--device', default='cuda')
+        args = parser.parse_args(argv)
+        from .separate import separate_file
+        code = 'separation_failed'
+        paths, numbers = separate_file(args.source, args.out, args.weights, device=args.device)
+        result = dict(ok=True, paths={name: str(Path(path)) for name, path in paths.items()}, **numbers)
+        status = 0
+    except Exception as exc:
+        try:
+            import torch
+            if isinstance(exc, torch.cuda.OutOfMemoryError):
+                code = 'out_of_memory'
+        except ImportError:
+            pass
+        if isinstance(exc, FileNotFoundError):
+            code = 'model_missing'
+        elif type(exc).__name__ == 'SeparationError' and exc.args:
+            code = str(exc.args[0])
+        result = dict(ok=False, error=code, detail=str(exc)[:2000])
+        status = 1
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+    return status
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/web/editor.css b/web/editor.css
index 3a00990c..41d3bb69 100644
--- a/web/editor.css
+++ b/web/editor.css
@@ -55,6 +55,7 @@
 .fv-ed-preview-close svg{width:16px;height:16px;fill:none;stroke:currentColor;stroke-width:1.4;stroke-linecap:round}
 .fv-editor .fv-ed-play:disabled{opacity:.4}
 .fv-editor:has(.fv-ed-track-row[data-track=a2]){--fv-ed-tracks-min:220px}
+.fv-editor:has(.fv-ed-track-row[data-track=a4]){--fv-ed-tracks-min:330px}
 .fv-editor .fv-ed-track-view{height:100%}
 .fv-ed-picture>video{position:absolute;width:100%;height:100%;inset:0;object-fit:contain;opacity:0;pointer-events:none}
 .fv-ed-picture>video.fv-ed-visible{opacity:1}
diff --git a/web/editor.js b/web/editor.js
index 815c31cf..97395550 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -22,6 +22,7 @@ import {pictureSession} from './editor_picture_session.js';
 import {createPictureTools} from './editor_frame.js';
 import {openExportDialog} from './editor_export_dialog.js';
 import {createAudioIntegration, createSpeechSpans, handleAudioShortcut, AUDIO_SHORTCUTS} from './editor_audio.js';
+import {createStemsIntegration} from './editor_stems.js';
 import {createSpeedComponent, readSpeedAudioSamples, handleSpeedKey, speedShortcuts} from './editor_speed.js';
 import {createEditorGenbar, loadEditorComponents, editorBlockStates, blockMessages} from './editor_genbar.js';
 import {createEditorMusic} from './editor_music.js';
@@ -254,7 +255,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
     let discardOnSwitch = false, initialSelection = null, offerInitial = null, extendEntry = null;
     let viewKey = null, viewReady = false;
     let library = null, closing = false, closePromise = null, exportSnapshot = null, lastSeed = null, projectEpoch = 0;
-    let disposed = false, suppressSave = false, savedContent = '', initializing = true, tracks = null, genbar = null, adjustPanel = null, exportStatus = null, pointerEditing = false, deferredStamp = null;
+    let stems = null, disposed = false, suppressSave = false, savedContent = '', initializing = true, tracks = null, genbar = null, adjustPanel = null, exportStatus = null, pointerEditing = false, deferredStamp = null;
     let capability = {maxSeconds: 15, maxFollowSeconds: 15, maxRequestFrames: null, estimate: () => null}, generationBusy = false, switching = false, generationDone = null, finishGeneration = null;
     let noticeTimer = null, stopExport = null, mostRecentJob = null, exportPreparing = false, guide = null;
     const jobWatchers = new Map(), progress = new Map(), jobStatuses = new Map(), runProgress = new Map();
@@ -1141,6 +1142,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         },
         async cancel() {
             if (music.target()) { await music.cancel(); return; }
+            if (stems?.active()) { await stems.cancel(); return; }
             const range = selectionRange(state.selection);
             const own = range && state.record.tracks[0].clips.find(clip => clip.job && generating(clip)
                 && clip.start < range.start + range.frames && clip.start + clip.frames > range.start)?.job;
@@ -1314,9 +1316,11 @@ export function openEditor({api, app, from = null, panel = {}, components: given
     const transportControls = createEditorTransport({element, preview, transport, toolbar, editTools, zoomHost, state, player, t, notify});
     toolbar.append(adjust.toggleButton);
     const textTools = createEditorText({element, state, t, actions, adjust, player, toolbar, exportBox, tracksHost});
-    const toolbarMore = createToolbarMore({toolbar, t, keep: '.fv-ed-undo, .fv-ed-split, .fv-ed-delete, .fv-ed-adjust-toggle, .fv-ed-zoom'});
+    const toolbarMore = createToolbarMore({toolbar, t, keep: '.fv-ed-undo, .fv-ed-split, .fv-ed-delete, .fv-ed-adjust-toggle, .fv-ed-zoom, .fv-ed-stems-button'});
     actions.speech.ability().then(value => { if (!disposed) textTools.speech(value); }).catch(() => {});
     const audio = createAudioIntegration({state, player, t, error, adjust, library: libraryHost, store});
+    stems = createStemsIntegration({state, api, queue, store, t, error, notify, toolbar, show: job => genbar?.update(job),
+        restore: () => genbar?.update(mostRecentJob ? barJob(jobStatuses.get(mostRecentJob)) : null)});
     registerEditorShortcuts(AUDIO_SHORTCUTS, speedShortcuts);
     adjust.register('speed', createSpeedComponent({state, t, onError: error}));
     function selectedContent() {
@@ -1521,7 +1525,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 await store.activateProject(null).catch(() => {});
                 rememberView(); disposed = true; music.dispose(); guide?.dispose(); transportControls.dispose(); toolbarMore.dispose(); player.dispose();
                 textTools.dispose(); adjust.dispose(); notes.dispose(); pictureEdit.dispose();
-                audio.dispose(); headerFit.dispose();
+                audio.dispose(); stems?.dispose(); headerFit.dispose();
                 listeners.splice(0).forEach(remove => remove());
                 for (const node of [element, ...element.querySelectorAll('*')]) for (const name of ['onclick', 'ondblclick', 'oninput', 'onchange', 'onkeydown', 'ondragstart']) node[name] = null;
                 unsubscribe(); stopSources(); library?.dispose(); genbar.dispose(); tracks?.dispose(); stopExport?.();
diff --git a/web/editor_audio_model.js b/web/editor_audio_model.js
index dcc05460..5d392201 100644
--- a/web/editor_audio_model.js
+++ b/web/editor_audio_model.js
@@ -28,6 +28,14 @@ export function audioClipFields(raw, kind) {
         if (kind !== 'audio' || typeof raw.duck !== 'boolean') fail('audio');
         fields.duck = raw.duck;
     }
+    if (raw.stem_of !== undefined) {
+        if (kind !== 'audio' || typeof raw.stem_of !== 'string' || !/^c[1-9]\d{0,8}$/.test(raw.stem_of) || raw.stem_of === raw.id || raw.link) fail('stems');
+        fields.stem_of = raw.stem_of;
+    }
+    if (raw.stem_volume !== undefined) {
+        if (kind !== 'audio' || typeof raw.stem_volume !== 'number' || !(raw.stem_volume >= 0 && raw.stem_volume <= 2)) fail('stems');
+        fields.stem_volume = raw.stem_volume;
+    }
     return fields;
 }
 export function audioTrackFields(raw) {
@@ -39,6 +47,11 @@ export function audioTrackFields(raw) {
     return fields;
 }
 export function normalizeAudioEdits(record) {
+    // A clip silenced for its separated sound speaks again once no stem clip refers to it.
+    const stemmed = new Set(record.tracks.flatMap(track => track.clips).map(clip => clip.stem_of));
+    for (const track of record.tracks) for (const clip of track.clips) {
+        if (clip.stem_volume !== undefined && !stemmed.has(clip.id)) { clip.volume = clip.stem_volume; delete clip.stem_volume; }
+    }
     for (const track of record.tracks) for (const clip of track.clips) {
         for (const name of ['fade_in', 'fade_out']) if (clip[name] !== undefined) clip[name] = Math.min(clip[name], Math.floor(clip.frames / 2));
     }
diff --git a/web/editor_menu.js b/web/editor_menu.js
index 52f6efc0..eff3e1b2 100644
--- a/web/editor_menu.js
+++ b/web/editor_menu.js
@@ -119,6 +119,7 @@ export function createTrackMenu(host, {state, t = en => en, actions = {}, hitTes
             const label = document.createElement('span'), shortcut = document.createElement('span');
             label.className = 'fv-ed-menu-label'; label.textContent = item.label;
             shortcut.className = 'fv-ed-menu-shortcut'; shortcut.textContent = item.shortcut;
+            if (item.tourId) button.dataset.tourId = item.tourId;
             button.append(label, shortcut);
             // Keep disabled items discoverable without explanatory tooltips.
             button.onclick = () => {
@@ -133,7 +134,9 @@ export function createTrackMenu(host, {state, t = en => en, actions = {}, hitTes
         const width = window.innerWidth || document.documentElement?.clientWidth || 1440;
         const height = window.innerHeight || document.documentElement?.clientHeight || 900;
         element.style.left = `${Math.max(8, Math.min(event.clientX, width - bounds.width - 8))}px`;
-        element.style.top = `${Math.max(8, Math.min(event.clientY, height - bounds.height - 8))}px`;
+        // Without room below the pointer the menu opens upward from it, so it never slides over the toolbar beside it.
+        const below = event.clientY + bounds.height + 8 <= height;
+        element.style.top = `${Math.max(8, below ? event.clientY : event.clientY - bounds.height)}px`;
         (buttons[0] || element).focus({preventScroll: true});
     };
     const outside = event => { if (!element.contains(event.target)) close(); }, closeMenu = () => close();
diff --git a/web/editor_model.js b/web/editor_model.js
index d34926f0..a18497ad 100644
--- a/web/editor_model.js
+++ b/web/editor_model.js
@@ -15,7 +15,7 @@ export const RULES = Object.freeze({maxSeconds: 15, singleSeconds: 30, minSecond
     followSeconds: CHAIN_RULES.min_part_seconds, fullSeconds: CHAIN_RULES.full_part_seconds,
     continueSeconds: CHAIN_RULES.continue_seconds, shortContinueSeconds: CHAIN_RULES.short_continue_seconds,
     step: 17, first: 5, overlap: 22,
-    maxTracks: 3, maxClips: 500, maxText: 8000, maxParts: CHAIN_RULES.max_parts, shortMaxParts: CHAIN_RULES.short_max_parts});
+    maxTracks: 7, maxClips: 500, maxText: 8000, maxParts: CHAIN_RULES.max_parts, shortMaxParts: CHAIN_RULES.short_max_parts});
 // Slice and bound user text by Unicode code points, never UTF-16 halves.
 export const truncateText = (text, limit) => Array.from(text).slice(0, limit).join('');
 export const copyName = (name, suffix) => truncateText(name, RULES.maxText - Array.from(suffix).length) + suffix;
@@ -137,11 +137,14 @@ export function parse(value) {
     check(value.settings === null || object(value.settings), 'settings');
     const settings = jsonData(value.settings);
     check(JSON.stringify(settings).length <= 1024 * 1024, 'settings');
-    check(Array.isArray(value.tracks) && value.tracks.length >= 2 && value.tracks.length <= RULES.maxTracks, 'track');
+    check(Array.isArray(value.tracks) && value.tracks.length >= 2 && value.tracks.length <= RULES.maxTracks
+        && value.tracks.length !== 4 && value.tracks.length !== 5 && value.tracks.length !== 6, 'track');
     const ids = new Set();
     const tracks = value.tracks.map((raw, index) => {
-        const id = ['v1', 'a1', 'a2'][index], kind = index === 0 ? 'video' : 'audio';
+        const id = ['v1', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6'][index], kind = index === 0 ? 'video' : 'audio';
         check(object(raw) && raw.id === id && raw.kind === kind, 'track');
+        // The three tracks after a3 are the separated sound of one clip each: all of them or none.
+        check(index < 4 ? raw.stem === undefined : raw.stem === STEM_TRACKS[index - 4], 'track');
         check(Array.isArray(raw.clips) && raw.clips.length <= RULES.maxClips, 'track');
         let boundary = 0;
         const clips = raw.clips.map(item => {
@@ -188,7 +191,7 @@ export function parse(value) {
             Object.assign(clip, parseSpeedData(item, kind));
             return clip;
         });
-        return {id, kind, clips, ...audioTrackFields(raw)};
+        return {id, kind, clips, ...audioTrackFields(raw), ...(raw.stem !== undefined ? {stem: raw.stem} : {})};
     });
     const byId = new Map(tracks.flatMap(track => track.clips.map(clip => [clip.id, {clip, track}])));
     for (const {clip, track} of byId.values()) if (clip.link) {
@@ -498,6 +501,32 @@ export function insertSource(record, {source, frames, hasVideo, hasAudio, width,
     if (words && storedSize(result) > STORED_ROOM) return insertSource(record, {source: given, frames, hasVideo, hasAudio, width, height, at: position, targetTrack});
     return result;
 }
+// The separated sound of an audio clip: three tracks after a2 hold one clip each (dialogue, music, ambience)
+// over the parent's range, and the parent goes silent. Deleting every stem clip gives the parent its volume back
+// (normalizeAudioEdits), so the silence needs no separate undo.
+export const STEM_TRACKS = Object.freeze(['dialogue', 'music', 'ambience']);
+export function placeStems(record, id, sources) {
+    const next = copy(record), parent = find(next, id);
+    check(parent && trackOf(next, id).kind === 'audio' && parent.source && !parent.pending, 'missing');
+    check(!trackOf(next, id).locked, 'locked');
+    check(!all(next).some(clip => clip.stem_of === id), 'stems');
+    check(object(sources) && STEM_TRACKS.every(name => object(sources[name])), 'source');
+    audioTrack(next, 'a2'); audioTrack(next, 'a3');
+    const rows = ['a4', 'a5', 'a6'].map((track, index) => {
+        const row = audioTrack(next, track); row.stem = STEM_TRACKS[index];
+        check(!row.locked && !row.clips.some(clip => overlaps(clip, parent.start, parent.frames)), 'audio_full');
+        return row;
+    });
+    const volume = parent.volume;
+    rows.forEach((row, index) => {
+        const clip = newClip(next, row, {source: sourceData(sources[STEM_TRACKS[index]]), start: parent.start, frames: parent.frames});
+        for (const name of ['in', 'length', 'splice', 'speed', 'speed_audio', 'reverse', 'fade_in', 'fade_out'])
+            if (parent[name] !== undefined) clip[name] = JSON.parse(JSON.stringify(parent[name]));
+        clip.stem_of = id;
+    });
+    parent.stem_volume = volume; parent.volume = 0;
+    return finish(next);
+}
 export function move(record, id, start, {targetTrack} = {}) {
     if (isText(find(record, id))) return changeText(record, id, {start});
     check(whole(start), 'range'); const selected = pair(record, id); check(selected.length, 'missing'); busy(selected);
diff --git a/web/editor_player.js b/web/editor_player.js
index 000a8409..83d3ed1b 100644
--- a/web/editor_player.js
+++ b/web/editor_player.js
@@ -39,7 +39,8 @@ export function createEditorPlayer(host, transport, {state, sources, api, t, err
     const closeIcon = document.createElementNS(pictureIcon.namespaceURI, 'svg'), closePath = document.createElementNS(pictureIcon.namespaceURI, 'path');
     closeIcon.setAttribute('viewBox', '0 0 16 16'); closeIcon.setAttribute('aria-hidden', 'true'); closePath.setAttribute('d', 'm4 4 8 8M12 4l-8 8'); closeIcon.append(closePath); closePreview.append(closeIcon); frame.append(closePreview);
     const videos = [el('video'), el('video')]; videos.forEach(video => { video.playsInline = true; video.preload = 'auto'; video.controls = false; video.setAttribute('aria-hidden', 'true'); frame.append(video); });
-    const audio = [el('audio'), el('audio')]; audio.forEach(value => { value.preload = 'auto'; frame.append(value); });
+    // One element per sound track (a1–a6): the three separated parts play together with the voice and music tracks.
+    const audio = Array.from({length: 6}, () => el('audio')); audio.forEach(value => { value.preload = 'auto'; frame.append(value); });
     const chainAudio = new Map(); // Separate players keep the other track's media slot stable.
     const allMedia = () => [...videos, ...audio, ...chainAudio.values()];
     const pictureGuide = createPictureGuide(host, frame, {state, t});
diff --git a/web/editor_room.js b/web/editor_room.js
index f971e1f9..2494f63d 100644
--- a/web/editor_room.js
+++ b/web/editor_room.js
@@ -100,7 +100,7 @@ export function pasteContent(record, content, at) {
         if (isText(clip) && track.clips.some(other => other.start < end(clip) && end(other) > clip.start)) throw new EditError('overlap');
         track.clips.push(clip);
     }
-    next.tracks.sort((a,b) => ['v1','a1','a2','t1','s1'].indexOf(a.id) - ['v1','a1','a2','t1','s1'].indexOf(b.id));
+    next.tracks.sort((a,b) => ['v1','a1','a2','a3','a4','a5','a6','t1','s1'].indexOf(a.id) - ['v1','a1','a2','a3','a4','a5','a6','t1','s1'].indexOf(b.id));
     next.tracks.forEach(track => track.clips.sort((a, b) => a.start - b.start));
     return {record: model.parse(next), ids: [...ids.values()], end: Math.max(...entries.map(item => end(item.clip)))};
 }
diff --git a/web/editor_stems.js b/web/editor_stems.js
new file mode 100644
index 00000000..b99facc3
--- /dev/null
+++ b/web/editor_stems.js
@@ -0,0 +1,168 @@
+import * as model from './editor_model.js';
+import {registerMenuItem} from './editor_menu.js';
+import {agentGet, agentPost, retryAgentPost} from './agent_session.js';
+import {sourceKey} from './editor_store.js';
+
+const ROOT = '/freevideo/agent/v1';
+const ACTIVE = ['waiting', 'queued', 'running', 'cancelling'];
+// Answers the separation can end with; anything else is reported by the editor's own error line.
+const FAILURES = {
+    stems_download_failed: ['The separation model could not be downloaded. Check the network and try again.', '分离模型下载失败，请检查网络后重试。'],
+    out_of_memory: ['Not enough graphics memory to separate this sound.', '显存不足，无法分离这段声音。'],
+    stems_failed: ['The sound could not be separated. Try again.', '声音分离失败，请重试。'],
+    project_changed: ['The edit changed meanwhile. Try again.', '编辑内容已变化，请重试。'],
+    clip_busy: ['This clip is still being made.', '这个片段还在生成。'],
+    clip_locked: ['This clip is locked.', '这个片段已锁定。'],
+    audio_full: ['The tracks for the separated sound are not free here.', '这里没有空闲的分轨位置。'],
+};
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const generatedSource = text => {
+    const match = /^generated:(.+)$/.exec(String(text || ''));
+    if (!match) throw new model.EditError('source');
+    return {kind: 'generated', id: match[1]};
+};
+const children = (record, id) => record.tracks.flatMap(track => track.clips).filter(clip => clip.stem_of === id);
+
+// A sound clip is split into dialogue, music and ambience. The job leaves the project alone (lay: false); this page
+// places the three parts itself, so its own saves never clash with the job and the placement can be undone.
+export function createStemsIntegration({state, api, queue, store, t, error, notify, show, restore, toolbar}) {
+    let running = null, disposed = false, available = false, unsubscribe = null;
+    const say = (value, fallback) => {
+        const code = value?.code || value?.error?.code, text = FAILURES[code];
+        if (text) notify(t(...text)); else error(value?.error || value || new Error(fallback), 'stems');
+    };
+    const phaseWords = progress => {
+        const detail = (() => { try { return JSON.parse(progress?.detail || 'null'); } catch { return null; } })();
+        switch (progress?.phase) {
+            case 'downloading': return Number.isFinite(detail?.fraction)
+                ? t(`Downloading the separation model ${Math.round(detail.fraction * 100)}%`, `正在下载分离模型 ${Math.round(detail.fraction * 100)}%`)
+                : t('Downloading the separation model', '正在下载分离模型');
+            case 'separating': return t('Separating the sound', '正在分离声音');
+            case 'waiting': return t('Waiting for the video to finish', '等待视频生成完成');
+            case 'placing': return t('Adding the tracks', '正在放入时间线');
+            default: return t('Preparing', '正在准备');
+        }
+    };
+    const paint = (job, stage) => show({id: `stems:${job}`, state: 'running', blocks: [], words: {stage}});
+    const parent = context => context.count === 1 && context.clip;
+    const splittable = context => {
+        const clip = parent(context), track = clip && context.record.tracks.find(row => row.clips.includes(clip));
+        return !!clip && track?.kind === 'audio' && !!clip.source && !clip.pending && clip.stem_of === undefined
+            && !track.locked && !children(context.record, clip.id).length && !running;
+    };
+    const stemmed = context => !!parent(context) && children(context.record, context.clip.id).length > 0;
+    // The sound clip the toolbar button acts on: the one sound clip inside the selection, whether it was picked alone or with its picture.
+    const target = () => {
+        const selection = state.selection;
+        if (selection?.kind !== 'clip') return null;
+        const sound = state.record.tracks.filter(track => track.kind === 'audio')
+            .flatMap(track => track.clips.filter(clip => selection.ids.includes(clip.id)).map(clip => ({clip, track})));
+        return sound.length === 1 && !!sound[0].clip.source && sound[0].clip.stem_of === undefined ? sound[0] : null;
+    };
+    let button = null, holder = null;
+    const sync = () => {
+        if (!button) return;
+        const found = available && target();
+        button.hidden = holder.hidden = !found;
+        if (!found) return;
+        const {clip, track} = found;
+        button.disabled = !!running || !!clip.pending || track.locked || children(state.record, clip.id).length > 0;
+    };
+    // The entries exist only where the engine offers the separation, so other computers keep the menu they had.
+    let stops = [];
+    const capability = (async () => {
+        try {
+            const response = await api.fetchApi('/freevideo/stems-support', {cache: 'no-store'});
+            const value = response.ok ? await response.json() : null;
+            available = value?.available === true;
+        } catch { available = false; }
+        if (available && !disposed && toolbar) {
+            const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+            svg.setAttribute('viewBox', '0 0 16 16'); svg.setAttribute('aria-hidden', 'true'); svg.classList.add('fv-ed-glyph');
+            const path = document.createElementNS(svg.namespaceURI, 'path');
+            path.setAttribute('d', 'M2 8h1.5M5 5v6M8 3v10M11 5.5v5M14 8h-1'); path.setAttribute('fill', 'none'); path.setAttribute('stroke', 'currentColor');
+            path.setAttribute('stroke-width', '1.4'); path.setAttribute('stroke-linecap', 'round'); svg.append(path);
+            const text = document.createElement('span'); text.className = 'fv-ed-stems-label'; text.textContent = t('Separate tracks', '分离音轨');
+            button = document.createElement('button'); button.type = 'button'; button.className = 'fv-action fv-ed-stems-button'; button.hidden = true;
+            button.setAttribute('aria-label', t('Separate tracks', '分离音轨')); button.title = t('Separate tracks', '分离音轨'); button.dataset.tourId = 'audio-track-button';
+            button.append(svg, text);
+            button.onclick = () => { const found = target(); if (found && !button.disabled) void separate(found.clip.id); };
+            holder = document.createElement('div'); holder.className = 'fv-ed-tool-group fv-ed-stems-group'; holder.hidden = true; holder.append(button);
+            const anchor = toolbar.querySelector('.fv-ed-split')?.closest('.fv-ed-tool-group');
+            if (anchor) anchor.after(holder); else toolbar.insertBefore(holder, toolbar.querySelector('.fv-ed-zoom'));
+            unsubscribe = state.subscribe(event => { if (event.type === 'selection' || event.type === 'record') sync(); });
+            sync();
+        }
+        if (available && !disposed) stops = [
+            registerMenuItem({where: 'part', group: 'sound', label: context => context.t('Separate tracks', '分离音轨'),
+                enabled: splittable, tourId: 'audio-track-entry', run: context => { void separate(context.clip.id); }}),
+            registerMenuItem({where: 'part', group: 'sound', label: context => context.t('Export stems', '导出分轨'),
+                enabled: stemmed, run: context => { void exportStems(context.clip.id); }}),
+        ];
+    })();
+    async function ready() {
+        await capability;
+        if (!available) { notify(t('Separating audio is not available on this computer.', '这台电脑暂不支持分离音轨。')); return false; }
+        await queue.flush();
+        if (queue.dirty || !state.record.id) { notify(t('The edit could not be saved yet. Try again.', '编辑内容尚未保存，请稍后重试。')); return false; }
+        return true;
+    }
+    async function separate(clipId) {
+        if (running) { notify(t('A sound is already being separated.', '正在分离另一段声音。')); return false; }
+        const tool = running = {cancelled: false, job: null}; sync();
+        try {
+            if (!await ready()) return false;
+            const project = state.record.id, ref = globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random()}`;
+            const body = {revision: state.record.revision, clip_id: clipId, lay: false, ref};
+            paint('start', phaseWords());
+            const response = await retryAgentPost(api, `${ROOT}/projects/${encodeURIComponent(project)}/stems`, body);
+            const answer = await response?.json().catch(() => null);
+            if (!response?.ok || !answer?.job?.id && !answer?.jobs?.[0]?.id) { say(answer, 'stems_failed'); return false; }
+            tool.job = (answer.job || answer.jobs[0]).id;
+            let job = answer.job || answer.jobs[0];
+            while (!disposed && ACTIVE.includes(job.status)) {
+                paint(tool.job, tool.cancelled ? t('Stopping…', '正在停止…') : job.status === 'queued' || job.status === 'waiting' ? t('Queued', '排队中') : phaseWords(job.progress));
+                const reply = await agentGet(api, `${ROOT}/jobs/${encodeURIComponent(tool.job)}?wait=25`);
+                if (!reply.ok) { await wait(1000); continue; }
+                job = await reply.json();
+            }
+            if (disposed || state.record.id !== project) return false;
+            if (job.status !== 'succeeded') {
+                if (job.status !== 'cancelled' && !tool.cancelled) say(job.error, 'stems_failed');
+                return false;
+            }
+            const sources = Object.fromEntries(model.STEM_TRACKS.map(name => [name, generatedSource(job.result?.sources?.[name])]));
+            await store.getSources(Object.values(sources).map(sourceKey));
+            if (disposed || state.record.id !== project) return false;
+            try {
+                state.apply(t('Separate tracks', '分离音轨'), record => model.placeStems(record, clipId, sources));
+            } catch (value) {
+                if (value instanceof model.EditError) notify(t(...FAILURES[value.code === 'audio_full' ? 'audio_full' : 'stems_failed'])); else error(value, 'stems');
+                return false;
+            }
+            return true;
+        } catch (value) {
+            if (value?.name !== 'AbortError') say(value, 'stems_failed');
+            return false;
+        } finally { running = null; sync(); restore(); }
+    }
+    async function cancel() {
+        const tool = running; if (!tool) return false;
+        tool.cancelled = true;
+        if (tool.job) await agentPost(api, `${ROOT}/jobs/${encodeURIComponent(tool.job)}/cancel`, {}).catch(() => {});
+        return true;
+    }
+    async function exportStems(clipId) {
+        try {
+            if (!await ready()) return false;
+            const body = {revision: state.record.revision, clip_id: clipId, ref: globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random()}`};
+            const response = await retryAgentPost(api, `${ROOT}/projects/${encodeURIComponent(state.record.id)}/stems/export`, body);
+            const answer = await response?.json().catch(() => null);
+            if (!response?.ok) { say(answer, 'stems_failed'); return false; }
+            notify(t(`Saved the tracks to ${answer.folder}`, `分轨已保存到 ${answer.folder}`));
+            return true;
+        } catch (value) { say(value, 'stems_failed'); return false; }
+    }
+    return {separate, cancel, exportStems, active: () => !!running,
+        dispose() { disposed = true; stops.forEach(stop => stop()); stops = []; unsubscribe?.(); holder?.remove(); button = holder = null; }};
+}
diff --git a/web/editor_text_model.js b/web/editor_text_model.js
index 944f1072..7ed10595 100644
--- a/web/editor_text_model.js
+++ b/web/editor_text_model.js
@@ -59,7 +59,7 @@ export function readTextProject(raw, parseMedia) {
     }
     const style = cleanStyle(raw.subtitle_style, 'subtitle');
     if (Object.keys(style).length && result.tracks.some(t => t.kind === 'subtitle')) result.subtitle_style = style;
-    result.tracks.sort((a,b) => ['v1','a1','a2','t1','s1'].indexOf(a.id) - ['v1','a1','a2','t1','s1'].indexOf(b.id));
+    result.tracks.sort((a,b) => ['v1','a1','a2','a3','a4','a5','a6','t1','s1'].indexOf(a.id) - ['v1','a1','a2','a3','a4','a5','a6','t1','s1'].indexOf(b.id));
     return freeze(result);
 }
 export function assertUnlocked(record, ids) {
diff --git a/web/editor_tracks.css b/web/editor_tracks.css
index dd581c82..bd5929ac 100644
--- a/web/editor_tracks.css
+++ b/web/editor_tracks.css
@@ -46,6 +46,8 @@
 .fv-ed-block-progress{display:none}
 .fv-ed-clip[data-state=running] .fv-ed-block-progress,.fv-ed-block-progress[data-queued=true]{display:block}
 .fv-ed-clip[data-state=failed]{border:1px solid color-mix(in srgb,var(--fv-warning) 60%,transparent);background:color-mix(in srgb,var(--fv-warning) 12%,transparent);cursor:grab}
+.fv-ed-clip[data-split=true]{background:repeating-linear-gradient(to bottom,color-mix(in srgb,var(--fv-ink) 6%,transparent) 0 33.33%,transparent 33.33% 66.66%,color-mix(in srgb,var(--fv-ink) 6%,transparent) 66.66% 100%)}
+.fv-ed-clip[data-split=true] .fv-ed-clip-media{opacity:.35}
 .fv-ed-clip-status{position:absolute;left:10px;right:4px;top:50%;transform:translateY(-50%);display:flex;align-items:center;gap:4px;font-size:12px;white-space:nowrap;overflow:hidden;color:var(--fv-warning);pointer-events:none}
 .fv-ed-clip-status svg{width:12px;height:12px;flex:none;fill:none;stroke:currentColor;stroke-width:1.5;stroke-linecap:round}
 .fv-ed-clip-failure-reason{overflow:hidden;text-overflow:ellipsis}
@@ -82,7 +84,7 @@
 .fv-ed-clip-popover button+button{margin-left:6px}
 .fv-ed-clip-popover{max-height:calc(100% - 16px);overflow:auto}
 .fv-ed-track-view [hidden]{display:none!important}
-@media(max-width:520px){.fv-ed-track-view{--fv-ed-head-width:32px}.fv-ed-track-head>span:first-of-type{display:none}.fv-ed-track-zoom{right:8px}.fv-ed-clip-status{left:5px;font-size:11px}}
+@media(max-width:520px){.fv-ed-track-view,.fv-studio.fv-editor .fv-ed-track-view[data-track-switches],.fv-studio.fv-editor[data-text-tracks] .fv-ed-track-view{--fv-ed-head-width:52px}.fv-studio.fv-editor .fv-ed-track-head>svg{display:none}.fv-ed-track-head{padding:0 2px;box-sizing:border-box}.fv-ed-track-head>span:first-of-type{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:11px}.fv-ed-track-zoom{right:8px}.fv-ed-clip-status{left:5px;font-size:11px}}
 @media(forced-colors:active){.fv-ed-clip,.fv-ed-selection,.fv-ed-gesture-preview{border-color:Highlight}.fv-ed-playhead,.fv-ed-snap-line{background:CanvasText}}
 
 /* Gesture affordances; track slots and heads are owned by the track layout. */
@@ -106,3 +108,9 @@
 .fv-ed-selection.fv-ed-range-blocked .fv-ed-planned-label{color:var(--fv-danger)}
 .fv-ed-track-view[data-cursor=not-allowed] .fv-ed-track-content,.fv-ed-track-view[data-cursor=not-allowed] .fv-ed-track-content *{cursor:not-allowed}
 .fv-ed-clip.fv-ed-tiny{z-index:3;border-radius:0}
+.fv-editor .fv-ed-toolbar .fv-ed-stems-button{width:auto;padding:0 10px}
+.fv-editor .fv-ed-toolbar .fv-ed-stems-button[hidden]{display:none}
+.fv-editor .fv-ed-toolbar .fv-ed-stems-button .fv-ed-glyph{width:16px;height:16px;flex:none}
+@media(max-width:520px){.fv-editor .fv-ed-toolbar .fv-ed-stems-button{width:32px;padding:0}.fv-ed-stems-label{display:none}}
+.fv-editor .fv-ed-toolbar .fv-ed-stems-group{margin-left:-8px}.fv-editor .fv-ed-toolbar .fv-ed-stems-group:before{display:none}.fv-ed-stems-group[hidden]{display:none}
+@media(max-width:480px){.fv-editor .fv-ed-toolbar .fv-ed-stems-group{margin-left:0}}
diff --git a/web/editor_tracks.js b/web/editor_tracks.js
index 66f94e73..1e8e79d3 100644
--- a/web/editor_tracks.js
+++ b/web/editor_tracks.js
@@ -492,12 +492,16 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
         const openFailure = !popover.hidden && failedPopoverId;
         selectGestures.finish(null, true);
         cachedPlan = ''; popover.hidden = true;
-        const record = state.record, retained = new Set(), tracks = displayTracks(record);
+        const record = state.record, retained = new Set();
+        // The model keeps a2 and a3 so the separated parts sit at fixed places; while they hold nothing they stay out of sight.
+        const separated = record.tracks.some(track => track.stem);
+        const tracks = displayTracks(record).filter(track => !(separated && track.kind === 'audio' && !track.stem && track.id !== 'a1' && !track.clips.length));
         const twoAudio = tracks.some(track => track.id === 'a2');
-        let top = 24;
+        const STEM_NAMES = {dialogue: t('Dialogue', '人声'), music: t('Music', '音乐'), ambience: t('Ambience', '环境声')};
+        let top = 24, parted = false;
         for (const track of tracks) {
-            const name = track.kind === 'text' ? t('Text', '文字') : track.kind === 'subtitle' ? t('Subtitles', '字幕') : track.kind === 'video' ? t('Video', '画面') : twoAudio
-                ? t(`Audio ${track.id === 'a1' ? 1 : 2}`, `声音 ${track.id === 'a1' ? 1 : 2}`) : t('Audio', '声音');
+            const name = track.kind === 'text' ? t('Text', '文字') : track.kind === 'subtitle' ? t('Subtitles', '字幕') : track.kind === 'video' ? t('Video', '画面') : track.stem ? STEM_NAMES[track.stem] : twoAudio
+                ? t(`Audio ${track.id.slice(1)}`, `声音 ${track.id.slice(1)}`) : t('Audio', '声音');
             let row = rows.get(track.id);
             if (!row) {
                 const node = create('div', 'fv-ed-track-row'); node.dataset.track = track.id;
@@ -507,7 +511,7 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
                 const head = create('div', 'fv-ed-track-head'); head.dataset.track = track.id;
                 head.title = name; head.append(icon(track.kind), create('span', '', name));
                 heads.append(head); content.insertBefore(node, overlays);
-                row = {element: node, head, empty}; rows.set(track.id, row);
+                row = {element: node, head, empty}; rows.set(track.id, row); parted ||= !!track.stem;
             }
             row.head.title = name; row.head.querySelector('span').textContent = name;
             row.empty.hidden = track.clips.length > 0;
@@ -537,6 +541,7 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
                 previous = item.element;
                 const visual = model.clipState(clip), key = sourceKey(clip);
                 item.element.dataset.state = visual; item.element.dataset.track = track.id;
+                item.element.dataset.split = String(track.kind === 'audio' && clip.stem_of === undefined && state.record.tracks.some(row => row.stem && row.clips.some(other => other.stem_of === clip.id)));
                 item.element.dataset.busy = String(busy(clip)); item.element.dataset.extend = String(clip.extend && actions.generationAvailable?.() !== false && !busy(clip));
                 // A part not generated yet is attached only to the part it continues; drawn on its own it stays a separate block.
                 // Touching blocks are one video only when the later one continues the earlier one, or both are consecutive stretches of one source;
@@ -587,6 +592,8 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
         addAudio.setAttribute('aria-label', addAudio.textContent);
         setTrackHeight(top - 6);
         layout();
+        // The parts of a fresh split appear under the sound they came from: show them from the top.
+        if (parted) scroll.scrollTop = 0;
         const failure = openFailure && clips.get(openFailure);
         if (failure && model.clipState(failure.clip) === 'failed' && state.selection?.ids?.includes(openFailure)) failedPopover(failure);
         if (gesture?.type === 'move' && pointerEvent) updatePointer(pointerEvent);
diff --git a/web/health.js b/web/health.js
index 80becefd..7abb15fd 100644
--- a/web/health.js
+++ b/web/health.js
@@ -14,7 +14,7 @@ const t = (en, zh) => cn ? zh : en;
 const launchVisit = query.get('freevideo') === 'launch';
 // Every script this folder ships; a test keeps the list in step with web/*.js.
 export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_confirm_settings.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'chain_rules.js', 'timed_prompt.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
-    'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
+    'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_stems.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'image_lora.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
     'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',

From c1db179a23dfd4715214e94beb7c2cc7d61ea06c Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 18:03:27 +0000
Subject: [PATCH 06/26] Editor music: separated music can be replaced in place
 from the generation bar, with guide...

Editor music: separated music can be replaced in place from the generation bar, with guide targets on the sound lanes
---
 web/editor_genbar.js      |  7 ++++---
 web/editor_music.js       |  4 ++--
 web/editor_music_model.js | 42 ++++++++++++++++++++++++++++-----------
 web/editor_tracks.js      |  6 ++++++
 4 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/web/editor_genbar.js b/web/editor_genbar.js
index 7d2d3e4c..c8183c06 100644
--- a/web/editor_genbar.js
+++ b/web/editor_genbar.js
@@ -220,9 +220,10 @@ export function createEditorGenbar(host, {state, t, actions, text = ''}) {
             host.classList.toggle('fv-ed-genbar-music', !presets.hidden);
         }
         references?.update(busy, busy ? undefined : actions.references.visible() || false);
-        // A piece already made, failed or stopped is made again in place.
-        const made = musical && !!music.target(selection)?.clip && music.target(selection).clip.pending !== 'draft';
-        const verb = made ? t('Regenerate', '重新生成') : t('Generate', '生成');
+        // A piece already made, failed or stopped is made again in place; separated music is replaced in place.
+        const aimed = musical ? music.target(selection) : null;
+        const made = !!aimed?.clip && aimed.clip.pending !== 'draft';
+        const verb = aimed?.replace ? t('Replace music', '替换配乐') : made ? t('Regenerate', '重新生成') : t('Generate', '生成');
         generate.textContent = verb;
         // Never disabled for a reason the press itself can explain or fix; only until the server says it can generate.
         generate.disabled = busy || !!previewSelection || !!actions.generationWaiting?.();
diff --git a/web/editor_music.js b/web/editor_music.js
index ff39c665..49940933 100644
--- a/web/editor_music.js
+++ b/web/editor_music.js
@@ -119,7 +119,7 @@ export function createEditorMusic({state, store, t, completeSources = async () =
             if (!found?.clip || api.running({kind: 'clip', ids: [id]}) || found.clip.text === text) return false;
             state.apply(t('Edit description', '修改说明'), record => {
                 const next = JSON.parse(JSON.stringify(record));
-                next.tracks.find(track => track.id === music.MUSIC_TRACK).clips.find(clip => clip.id === id).text = text;
+                next.tracks.flatMap(track => track.clips).find(clip => clip.id === id).text = text;
                 return next;
             });
             return true;
@@ -152,7 +152,7 @@ export function createEditorMusic({state, store, t, completeSources = async () =
                 const pack = await Promise.resolve().then(() => store.musicPack()).catch(() => null);
                 if (pack && !pack.ready && pack.disk_ok === false) return {say: musicFailureText('disk_space', t)};
                 const pick = preset(); words = text.trim();
-                state.apply(t('Generate', '生成'), record => {
+                state.apply(found.replace ? t('Replace music', '替换配乐') : t('Generate', '生成'), record => {
                     const next = music.rememberPreset(record, pick);
                     if (id) return music.remakeMusic(next, id, {text: words, ...pick});
                     const planned = music.planMusic(next, {start: found.start, frames: found.frames, text: words, ...pick});
diff --git a/web/editor_music_model.js b/web/editor_music_model.js
index 2f020e99..40faeb31 100644
--- a/web/editor_music_model.js
+++ b/web/editor_music_model.js
@@ -14,12 +14,17 @@ export const MUSIC_MOODS = ['calm', 'upbeat', 'tense', 'warm', 'sad'];
 const fail = code => { throw new model.EditError(code); };
 const end = clip => clip.start + clip.frames;
 const lane = record => record.tracks.find(track => track.id === MUSIC_TRACK) || null;
+// Where music is made: the music track, and the music separated out of a sound clip, which new music can replace.
+const lanes = record => record.tracks.filter(track => track.kind === 'audio' && (track.id === MUSIC_TRACK || track.stem === 'music'));
+const laneOf = (record, id) => lanes(record).find(track => track.clips.some(clip => clip.id === id)) || null;
 
 // The music track's planned or running pieces: no file yet, waiting for (or made by) a music job.
-export const isMusicPart = (record, clip) => !!clip && !clip.source && clip.pending !== null
-    && !!lane(record)?.clips.some(other => other.id === clip.id);
+export const isMusicPart = (record, clip) => !!clip && !clip.source && clip.pending !== null && !!laneOf(record, clip.id);
 // A finished piece the music job made: its file sits in the music folder.
 export const isGeneratedMusic = clip => clip?.source?.kind === 'generated' && /^freevideo-music\/[a-z]+(-[a-z]+)?-[0-9a-f]{32}\.mp4$/.test(clip.source.id);
+// The music separated out of a sound clip, as separation left it.
+export const isSeparatedMusic = (record, clip) => !!clip?.stem_of && !!clip.source && !isGeneratedMusic(clip)
+    && laneOf(record, clip.id)?.stem === 'music';
 
 export const DEFAULT_PRESET = {style: 'cinematic', mood: 'calm'};
 const preset = value => MUSIC_STYLES.includes(value?.style) && MUSIC_MOODS.includes(value?.mood) ? {style: value.style, mood: value.mood} : null;
@@ -33,20 +38,24 @@ export function rememberPreset(record, value) {
     next.settings = {...(next.settings || {}), music: chosen};
     return model.parse(next);
 }
-// What a selection on the music track asks for: an empty stretch drawn or clicked there, or one piece of music
-// there (made again in place). Null for anything else.
+// What a selection asks for: an empty stretch drawn or clicked on the music track, one piece of music there or on
+// the separated music track (made again in place), or the separated music itself (replaced in place, `replace`).
+// Null for anything else.
 export function musicTarget(record, selection) {
+    if (!selection) return null;
     const track = lane(record);
-    if (!track || !selection) return null;
     if (selection.kind === 'range' && selection.tracks?.length === 1 && selection.tracks[0] === MUSIC_TRACK
         || selection.kind === 'gap' && selection.track === MUSIC_TRACK) {
+        if (!track) return null;
         const frames = Math.min(selection.frames, MAX_MUSIC_FRAMES);
         if (track.clips.some(clip => clip.start < selection.start + frames && end(clip) > selection.start)) return null;
         return {start: selection.start, frames};
     }
     if (selection.kind !== 'clip' || selection.ids.length !== 1) return null;
-    const clip = track.clips.find(clip => clip.id === selection.ids[0]);
-    if (!clip || !(isMusicPart(record, clip) || isGeneratedMusic(clip))) return null;
+    const clip = laneOf(record, selection.ids[0])?.clips.find(clip => clip.id === selection.ids[0]);
+    if (!clip) return null;
+    if (isSeparatedMusic(record, clip)) return clip.frames <= MAX_MUSIC_FRAMES ? {start: clip.start, frames: clip.frames, id: clip.id, clip, replace: true} : null;
+    if (!(isMusicPart(record, clip) || isGeneratedMusic(clip))) return null;
     return {start: clip.start, frames: clip.frames, id: clip.id, clip};
 }
 
@@ -67,15 +76,24 @@ export function planMusic(record, {start, frames, text = '', style, mood}) {
 }
 // Made again in place: a finished, failed or stopped piece becomes a planned one over the same stretch, with the
 // words and preset given; its volume, fades and lowering stay. One undo brings the previous piece back.
+// Separated music is replaced the same way: it stays a part of the clip it came from (deleting every separated
+// part still gives that clip its sound back), takes the music's own speed, and is lowered during speech.
 export function remakeMusic(record, id, {text = '', style, mood}) {
     if (typeof text !== 'string') fail('text');
     const chosen = preset({style, mood}) || fail('preset');
-    const next = model.serialize(record), clip = next.tracks.find(track => track.id === MUSIC_TRACK)?.clips.find(clip => clip.id === id);
-    if (!clip || !(isGeneratedMusic(clip) || !clip.source && clip.pending !== null)) fail('missing');
-    if (next.tracks.find(track => track.id === MUSIC_TRACK).locked) fail('locked');
+    const separated = isSeparatedMusic(record, model.find(record, id));
+    const next = model.serialize(record), track = next.tracks.find(track => track.clips.some(clip => clip.id === id));
+    const clip = laneOf(next, id) && track.clips.find(clip => clip.id === id);
+    if (!clip || !(separated || isGeneratedMusic(clip) || !clip.source && clip.pending !== null)) fail('missing');
+    if (separated && clip.frames > MAX_MUSIC_FRAMES) fail('too_long');
+    if (track.locked) fail('locked');
     if (['queued', 'running'].includes(clip.pending)) fail('busy');
     Object.assign(clip, {source: null, in: 0, length: clip.frames, text, pending: 'draft', reason: null, job: null, versions: [], music: chosen});
     delete clip.splice;
+    if (separated) {
+        for (const name of ['speed', 'speed_audio', 'speed_phase', 'reverse']) delete clip[name];
+        clip.duck = true;
+    }
     return model.parse(next);
 }
 
@@ -90,7 +108,7 @@ export function musicRequest(record, id, {seed} = {}) {
 }
 
 function change(record, id, job, edit) {
-    const next = model.serialize(record), clip = next.tracks.find(track => track.id === MUSIC_TRACK)?.clips.find(clip => clip.id === id);
+    const next = model.serialize(record), clip = laneOf(next, id)?.clips.find(clip => clip.id === id);
     if (!clip || clip.source || clip.pending === null) return null;
     if (job !== undefined && clip.job !== job) return null;
     edit(clip);
@@ -128,5 +146,5 @@ export function retryMusic(record, id) {
     }) ?? fail('missing');
 }
 // The pieces still waiting for a job after the page opens again, to watch or to mark failed.
-export const musicJobs = record => (lane(record)?.clips || []).filter(clip => !clip.source && clip.job && ['queued', 'running'].includes(clip.pending))
+export const musicJobs = record => lanes(record).flatMap(track => track.clips).filter(clip => !clip.source && clip.job && ['queued', 'running'].includes(clip.pending))
     .map(clip => ({id: clip.id, job: clip.job}));
diff --git a/web/editor_tracks.js b/web/editor_tracks.js
index 1e8e79d3..654a52ff 100644
--- a/web/editor_tracks.js
+++ b/web/editor_tracks.js
@@ -514,6 +514,10 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
                 row = {element: node, head, empty}; rows.set(track.id, row); parted ||= !!track.stem;
             }
             row.head.title = name; row.head.querySelector('span').textContent = name;
+            // Guide targets ("take me there"): the lanes where a range is dragged out for speech or music, and the
+            // separated music lane where new music replaces the old.
+            const tourId = track.stem === 'music' ? 'audio-music-stem' : track.stem ? '' : {a1: 'audio-a1-track', a2: 'audio-a2-track'}[track.id] || '';
+            if (tourId) row.element.dataset.tourId = tourId; else delete row.element.dataset.tourId;
             row.empty.hidden = track.clips.length > 0;
             // A picture track with any block description grows a strip for it under the pictures.
             const noted = !!actions.describedTrack?.(track); row.element.dataset.noted = String(noted);
@@ -590,6 +594,8 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
         addAudio.dataset.sign = addAudio.textContent.slice(0, 1); // Phone widths show the sign alone.
         addAudio.title = '';
         addAudio.setAttribute('aria-label', addAudio.textContent);
+        // Without Audio 2 the guide points at the button that adds it.
+        if (twoAudio) delete addAudio.dataset.tourId; else addAudio.dataset.tourId = 'audio-a2-track';
         setTrackHeight(top - 6);
         layout();
         // The parts of a fresh split appear under the sound they came from: show them from the top.

From 23e71037e49f8e9c294434fefcddb6b4814e4ee0 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 22:09:50 +0000
Subject: [PATCH 07/26] Cache reference, first-frame and reference-video
 latents by content hash

---
 freevideo_engine/encode_worker.py  |  78 +++++++++---
 freevideo_engine/input_cache.py    |   8 +-
 freevideo_engine/media_encoding.py | 191 +++++++++++++++++++++++++----
 3 files changed, 236 insertions(+), 41 deletions(-)

diff --git a/freevideo_engine/encode_worker.py b/freevideo_engine/encode_worker.py
index 4ceba4ec..7204effb 100644
--- a/freevideo_engine/encode_worker.py
+++ b/freevideo_engine/encode_worker.py
@@ -568,25 +568,65 @@ def attempt(index, failure):
             comfy.model_management.unload_all_models()
         gc.collect()
         comfy.model_management.soft_empty_cache()
-        from diffusers.modular_pipelines.minimax_h3.encoders import encode_vae_condition
-        from .vae_weights import load_video_encoder
-        from src.inference.render import PIXEL_MEAN, PIXEL_STD
-        vae_started = time.perf_counter()
-        if request.get('metrics'):
-            save(request['metrics'], {**loading, 'success': False, 'phase': 'keyframe_vae',
-                                     'load_seconds': load_seconds, 'prompt_encode_seconds': prompt_encode_seconds})
-        # Only the encoder is read; the decoder in the shared shards is skipped.
-        vae = (resident.input_video_encoder(request['base'], dict(width=width, height=height))
-               if resident is not None else load_video_encoder(request['base'])[0])
-        torch.cuda.synchronize()
-        keyframe_metrics['keyframe_vae_load_seconds'] = time.perf_counter() - vae_started
-        vae_started = time.perf_counter()
-        with torch.no_grad():
-            conditions = [encode_vae_condition(vae,
-                torch.from_numpy(np.array(image)).to('cuda').permute(2, 0, 1)[None, :, None],
-                PIXEL_MEAN, PIXEL_STD, 42).cpu() for image in images]
-        torch.cuda.synchronize()
-        keyframe_metrics['keyframe_vae_encode_seconds'] = time.perf_counter() - vae_started
+        from .paths import data_root
+        from .input_cache import digest
+        from .media_encoding import _latent_cache, _cached_latent, _remember_latent, make_latent_cache_key
+        cache_root = request.get('reference_latent_cache') or (data_root() / 'input-cache')
+        cache = _latent_cache(cache_root, request['base'], 'cuda')
+        conditions = [None, None]
+        keys = []
+        files = [keyframes['first'], keyframes['last']]
+        working_dir = Path(request['output']).parent / 'media'
+        working_dir.mkdir(parents=True, exist_ok=True)
+        for idx, img_file in enumerate(files):
+            c_hash = digest(img_file)
+            k = make_latent_cache_key(
+                content_hash=c_hash,
+                width=width,
+                height=height,
+                frames=1,
+                crop_mode='put_on_canvas',
+                base=request['base'],
+                device='cuda',
+                dtype='float32',
+            )
+            keys.append(k)
+            if cache is not None:
+                latent = _cached_latent(cache, k, working_dir)
+                if latent is not None:
+                    conditions[idx] = latent
+        if any(c is None for c in conditions):
+            from diffusers.modular_pipelines.minimax_h3.encoders import encode_vae_condition
+            from .vae_weights import load_video_encoder
+            from src.inference.render import PIXEL_MEAN, PIXEL_STD
+            vae_started = time.perf_counter()
+            if request.get('metrics'):
+                save(request['metrics'], {**loading, 'success': False, 'phase': 'keyframe_vae',
+                                         'load_seconds': load_seconds, 'prompt_encode_seconds': prompt_encode_seconds})
+            # Only the encoder is read; the decoder in the shared shards is skipped.
+            vae = (resident.input_video_encoder(request['base'], dict(width=width, height=height))
+                   if resident is not None else load_video_encoder(request['base'])[0])
+            torch.cuda.synchronize()
+            keyframe_metrics['keyframe_vae_load_seconds'] = time.perf_counter() - vae_started
+            vae_started = time.perf_counter()
+            with torch.no_grad():
+                for idx, (img, cond) in enumerate(zip(images, conditions)):
+                    if cond is None:
+                        cond = encode_vae_condition(vae,
+                            torch.from_numpy(np.array(img)).to('cuda').permute(2, 0, 1)[None, :, None],
+                            PIXEL_MEAN, PIXEL_STD, 42).cpu()
+                        conditions[idx] = cond
+                        if cache is not None:
+                            _remember_latent(cache, keys[idx], cond, working_dir)
+            torch.cuda.synchronize()
+            keyframe_metrics['keyframe_vae_encode_seconds'] = time.perf_counter() - vae_started
+            del vae
+            gc.collect()
+            comfy.model_management.soft_empty_cache()
+        else:
+            print(json.dumps({'event': 'keyframe_vae_cache_hit'}), flush=True)
+            keyframe_metrics['keyframe_vae_load_seconds'] = 0.
+            keyframe_metrics['keyframe_vae_encode_seconds'] = 0.
         value.update(keyframe_anchors=['first', 'last'], condition_latents=conditions,
                      keyframe_files=[keyframes['first'], keyframes['last']], width=width, height=height)
         from .keyframes import validate_conditioning
diff --git a/freevideo_engine/input_cache.py b/freevideo_engine/input_cache.py
index a7c0c4f1..29a7014b 100644
--- a/freevideo_engine/input_cache.py
+++ b/freevideo_engine/input_cache.py
@@ -121,7 +121,13 @@ def put(self, key, source, metrics, *, move=False):
             if digest(temporary) != checksum:
                 raise ValueError('Input changed during cache copy; partial retained')
             from .file_ops import publish
-            publish(temporary, target)
+            try:
+                publish(temporary, target)
+            except FileExistsError:
+                if not target.exists() or digest(target) != checksum:
+                    raise
+                if not move:
+                    temporary.unlink(missing_ok=True)
         receipt = self.receipt(key)
         if receipt.exists():
             # Keep old receipts too, including malformed ones, for diagnostics.
diff --git a/freevideo_engine/media_encoding.py b/freevideo_engine/media_encoding.py
index c3a7a446..9cc4c84e 100644
--- a/freevideo_engine/media_encoding.py
+++ b/freevideo_engine/media_encoding.py
@@ -145,13 +145,19 @@ def prepare(media, canvas, directory):
     for anchor in ('first', 'last'):
         if not media.get(anchor):
             continue
+        c_hash = media[anchor].get('sha256')
+        if not c_hash and media[anchor].get('path'):
+            from .input_cache import digest
+            c_hash = digest(media[anchor]['path'])
         with Image.open(media[anchor]['path']) as source:
             image = ImageOps.fit(ImageOps.exif_transpose(source).convert('RGB'),
                                  (canvas['width'], canvas['height']), method=Image.Resampling.LANCZOS)
         target = directory / (anchor + '.npy')
         np.save(target, np.array(image)[None], allow_pickle=False)
         key_images.append(torch.from_numpy(np.array(image)).float().div_(255)[None])
-        result.append({'kind': 'image', 'anchor': anchor, 'pixels': str(target), 'frames': 1})
+        result.append({'kind': 'image', 'anchor': anchor, 'pixels': str(target), 'frames': 1,
+                       'content_hash': c_hash, 'source_path': media[anchor]['path'],
+                       'width': canvas['width'], 'height': canvas['height'], 'crop_mode': 'fit'})
     for index, row in enumerate(media.get('references', [])):
         kind, path = row['kind'], row['path']
         if row.get('use') == 'original':
@@ -163,7 +169,11 @@ def prepare(media, canvas, directory):
                                audio=model_audio(info, canvas, target)))
             ref_items.append({'type': 'audio'})
             continue
-        ref = {'kind': kind}
+        c_hash = row.get('sha256')
+        if not c_hash and path:
+            from .input_cache import digest
+            c_hash = digest(path)
+        ref = {'kind': kind, 'content_hash': c_hash, 'source_path': path}
         if 'early_steps' in row:
             ref['early_steps'] = row['early_steps']
         if row.get('guide'):
@@ -174,9 +184,10 @@ def prepare(media, canvas, directory):
         if kind == 'image':
             with Image.open(path) as source:
                 image = ImageOps.exif_transpose(source).convert('RGB')
-                image = image.resize(reference_size(*image.size, canvas), Image.Resampling.LANCZOS)
+                target_w, target_h = reference_size(*image.size, canvas)
+                image = image.resize((target_w, target_h), Image.Resampling.LANCZOS)
             np.save(target, np.array(image)[None], allow_pickle=False)
-            ref.update(pixels=str(target), frames=1)
+            ref.update(pixels=str(target), frames=1, width=target_w, height=target_h, crop_mode='resize')
             ref_items.append({'type': 'image', 'data': torch.from_numpy(np.array(image)).float().div_(255)[None]})
         elif kind == 'video':
             import av
@@ -213,7 +224,7 @@ def prepare(media, canvas, directory):
                 if count < 22:
                     raise ValueError('The reference video is too short; it needs to be at least about 1 s long.')
                 pixels.flush()
-                ref.update(pixels=str(target), frames=count, normalized_fps=24)
+                ref.update(pixels=str(target), frames=count, normalized_fps=24, width=width, height=height, crop_mode='video_24fps')
                 used = count / 24.
                 # The clip's own sound is a reference too, unless the request turned it off.
                 soundtrack, longer_audio, _ = (None, False, None) if row.get('sound') is False or row.get('guide') else \
@@ -233,6 +244,7 @@ def prepare(media, canvas, directory):
             ref['audio'], longer, length = _audio(path, target, limit / 24.)
             if ref['audio'] is None:
                 raise ValueError('Reference audio file has no audio stream')
+            ref.update(width=0, height=0, frames=0, crop_mode='audio_32khz')
             ref_items.append({'type': 'audio'})
         if longer:
             # Numbered per kind like the prompt's <Video 1> and <Audio 1> tags.
@@ -255,10 +267,115 @@ def reference_options(normalized, options, step):
     return {'minimax_ref_items': items} if items else {}
 
 
+def vae_identity(base):
+    """File identity of the VAE encoder, matching existing model identity fields."""
+    from .input_cache import digest
+    directory = Path(base) / 'vae'
+    files = sorted(directory.glob('*.safetensors'))
+    if not files:
+        return None
+    return {
+        'config': digest(directory / 'config.json') if (directory / 'config.json').exists() else None,
+        'weights': [[f.name, f.stat().st_size, f.stat().st_mtime_ns] for f in files]
+    }
+
+
+def device_compute_capability(device):
+    """Hardware compute capability for CUDA/MPS/CPU."""
+    import torch
+    try:
+        dev = torch.device(device)
+        if dev.type == 'cuda':
+            if hasattr(torch, 'cuda') and hasattr(torch.cuda, 'is_available') and torch.cuda.is_available():
+                if hasattr(torch.cuda, 'get_device_capability'):
+                    return list(torch.cuda.get_device_capability(dev))
+            return None
+        elif dev.type == 'mps':
+            return 'mps'
+        return 'cpu'
+    except Exception:
+        return None
+
+
+def make_latent_cache_key(
+    content_hash,
+    width,
+    height,
+    frames,
+    crop_mode,
+    base=None,
+    device='cuda',
+    dtype='float32',
+    *,
+    model_identity=None,
+    code_version=None,
+    torch_version=None,
+    compute_capability=None,
+    return_dict=False,
+):
+    """Deterministic cache key containing all required material and environment properties."""
+    import hashlib
+    import torch
+    from . import __version__
+
+    if not content_hash or not isinstance(content_hash, str):
+        raise ValueError('Material file content hash is required')
+
+    if model_identity is None:
+        if base is not None:
+            model_identity = vae_identity(base)
+        else:
+            model_identity = None
+
+    if code_version is None:
+        # The release alone does not change between development builds, so the encoder code itself counts.
+        code_version = __version__ + ':' + hashlib.sha256(Path(__file__).read_bytes()).hexdigest()[:16]
+
+    if torch_version is None:
+        torch_version = getattr(torch, '__version__', 'unknown')
+
+    if compute_capability is None:
+        compute_capability = device_compute_capability(device)
+
+    if hasattr(dtype, '__name__'):
+        dtype_str = dtype.__name__
+    elif isinstance(dtype, str):
+        dtype_str = dtype
+    else:
+        dtype_str = str(dtype)
+
+    key_dict = {
+        'content_hash': str(content_hash),
+        'width': int(width),
+        'height': int(height),
+        'frames': int(frames),
+        'crop_mode': str(crop_mode),
+        'model_identity': model_identity,
+        'code_version': str(code_version),
+        'torch_version': str(torch_version),
+        'compute_capability': compute_capability,
+        'dtype': dtype_str,
+    }
+
+    serialized = json.dumps(key_dict, sort_keys=True, separators=(',', ':'))
+    key_string = 'latent-content-v1:' + hashlib.sha256(serialized.encode('utf-8')).hexdigest()
+
+    if return_dict:
+        return key_string, key_dict
+    return key_string
+
+
+def get_latent_cache_key_dict(**kwargs):
+    """Return the raw dictionary of cache key properties for verification."""
+    kwargs['return_dict'] = True
+    return make_latent_cache_key(**kwargs)[1]
+
+
 def _latent_cache(root, base, device):
     """Per-picture latent receipts; another encoder, recipe or device never matches."""
     import torch
     from .input_cache import InputCache, digest
+    from .paths import data_root
     directory = Path(base) / 'vae'
     files = sorted(directory.glob('*.safetensors'))
     if not files:
@@ -270,12 +387,13 @@ def _latent_cache(root, base, device):
     except Exception:
         diffusers = None
     from . import __version__
-    identity = {'recipe': 'reference-latent-v1', 'engine': __version__, 'diffusers': diffusers,
-                'torch': torch.__version__, 'device': kind,
-                'gpu': torch.cuda.get_device_name() if kind == 'cuda' else None,
+    identity = {'recipe': 'reference-latent-v2', 'engine': __version__, 'diffusers': diffusers,
+                'torch': getattr(torch, '__version__', 'unknown'), 'device': kind,
+                'gpu': torch.cuda.get_device_name() if (kind == 'cuda' and hasattr(torch, 'cuda') and hasattr(torch.cuda, 'is_available') and torch.cuda.is_available()) else None,
                 'config': digest(directory / 'config.json') if (directory / 'config.json').exists() else None,
                 'weights': [[f.name, f.stat().st_size, f.stat().st_mtime_ns] for f in files]}
-    return InputCache(identity, root=root, kind='reference-latent')
+    target_root = root or (data_root() / 'input-cache')
+    return InputCache(identity, root=target_root, kind='reference-latent')
 
 
 def _pixels_key(mapped):
@@ -287,29 +405,46 @@ def _pixels_key(mapped):
     return value.hexdigest()
 
 
-def _cached_latent(cache, key, directory):
+def _key_slug(key):
+    import hashlib
+    if isinstance(key, str) and len(key) == 64 and all(c in '0123456789abcdef' for c in key.lower()):
+        return key[:16]
+    return hashlib.sha256(str(key).encode('utf-8')).hexdigest()[:16]
+
+
+def _cached_latent(cache, key, directory=None):
     import torch
-    target = Path(directory) / ('reference-latent-' + key[:16] + '.hit.pt')
+    import uuid
+    if cache is None:
+        return None
+    staging_dir = Path(directory or cache.root)
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    target = staging_dir / ('reference-latent-' + _key_slug(key) + '-' + uuid.uuid4().hex + '.hit.pt')
     try:
         if cache.get(key, target) is None:
             return None
         latent = torch.load(target, map_location='cpu', weights_only=True)
         if isinstance(latent, torch.Tensor) and latent.is_floating_point() and bool(torch.isfinite(latent).all()):
             return latent
-    except (OSError, ValueError, RuntimeError, KeyError, TypeError, EOFError):
+    except Exception:
         pass
     finally:
         target.unlink(missing_ok=True)
     return None
 
 
-def _remember_latent(cache, key, latent, directory):
+def _remember_latent(cache, key, latent, directory=None):
     import torch
-    path = Path(directory) / ('reference-latent-' + key[:16] + '.save.pt')
+    import uuid
+    if cache is None or latent is None:
+        return
+    staging_dir = Path(directory or cache.root)
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    path = staging_dir / ('reference-latent-' + _key_slug(key) + '-' + uuid.uuid4().hex + '.save.pt')
     try:
         torch.save(latent, path)
         cache.put(key, path, {'success': True})
-    except (OSError, ValueError, RuntimeError):
+    except Exception:
         pass
     finally:
         path.unlink(missing_ok=True)
@@ -319,14 +454,13 @@ def encode_latents(normalized, value, base, canvas, *, resident=None, device='cu
     import gc
     import numpy as np
     import torch
-    from diffusers.modular_pipelines.minimax_h3.encoders import encode_vae_condition
-    from .vae_weights import load_audio_vae, load_video_encoder
-    from src.inference.render import PIXEL_MEAN, PIXEL_STD
+    from .paths import data_root
     if torch.device(device).type not in ('cuda', 'mps'):
         raise ValueError('Media encoding requires a CUDA or MPS device')
     empty_cache = torch.mps.empty_cache if torch.device(device).type == 'mps' else torch.cuda.empty_cache
     refs = [{key: row[key] for key in ('kind', 'early_steps', 'guide') if key in row} for row in normalized]
     keys, cache, hits = {}, None, set()
+    cache_root = cache_root or (data_root() / 'input-cache')
     if cache_root and any(row.get('pixels') for row in normalized):
         # The same picture or clip with another prompt reuses its latent and may skip loading the encoder.
         try:
@@ -334,9 +468,21 @@ def encode_latents(normalized, value, base, canvas, *, resident=None, device='cu
             for index, (row, ref) in enumerate(zip(normalized, refs)):
                 if cache is None or not row.get('pixels'):
                     continue
-                mapped = np.load(row['pixels'], mmap_mode='r', allow_pickle=False)
-                keys[index] = _pixels_key(mapped[:row['frames']])
-                del mapped
+                if row.get('content_hash'):
+                    keys[index] = make_latent_cache_key(
+                        content_hash=row['content_hash'],
+                        width=row.get('width', canvas.get('width', 0)),
+                        height=row.get('height', canvas.get('height', 0)),
+                        frames=row.get('frames', 1),
+                        crop_mode=row.get('crop_mode', 'fit'),
+                        base=base,
+                        device=device,
+                        dtype='float32',
+                    )
+                else:
+                    mapped = np.load(row['pixels'], mmap_mode='r', allow_pickle=False)
+                    keys[index] = _pixels_key(mapped[:row['frames']])
+                    del mapped
                 latent = _cached_latent(cache, keys[index], Path(row['pixels']).parent)
                 if latent is not None:
                     ref['latent'] = latent
@@ -346,6 +492,9 @@ def encode_latents(normalized, value, base, canvas, *, resident=None, device='cu
         print(json.dumps({'event': 'reference_latent_cache', 'hits': len(hits), 'misses': len(keys) - len(hits)}), flush=True)
     if any(row.get('pixels') for index, row in enumerate(normalized) if index not in hits):
         print(json.dumps({'event': 'media_encode_phase', 'phase': 'Encoding image/video references'}), flush=True)
+        from diffusers.modular_pipelines.minimax_h3.encoders import encode_vae_condition
+        from .vae_weights import load_video_encoder
+        from src.inference.render import PIXEL_MEAN, PIXEL_STD
         # Conditioning never decodes: the 9.0 GiB decoder in the shared shards
         # is not read. The independent output decoder is loaded after sampling.
         on_mps = torch.device(device).type == 'mps'

From c4fe05935b78cb3c119377e2f68130c9ab980948 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 18:12:39 +0000
Subject: [PATCH 08/26] Keyframe latent cache: first and last frames keep
 separate entries

Keyframe latent cache: first and last frames keep separate entries; cache only when the request names a root
---
 freevideo_engine/encode_worker.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/freevideo_engine/encode_worker.py b/freevideo_engine/encode_worker.py
index 7204effb..5e07be14 100644
--- a/freevideo_engine/encode_worker.py
+++ b/freevideo_engine/encode_worker.py
@@ -568,11 +568,15 @@ def attempt(index, failure):
             comfy.model_management.unload_all_models()
         gc.collect()
         comfy.model_management.soft_empty_cache()
-        from .paths import data_root
         from .input_cache import digest
         from .media_encoding import _latent_cache, _cached_latent, _remember_latent, make_latent_cache_key
-        cache_root = request.get('reference_latent_cache') or (data_root() / 'input-cache')
-        cache = _latent_cache(cache_root, request['base'], 'cuda')
+        # Only a request that names a cache root caches; profiling runs stay uncached.
+        cache = None
+        if request.get('reference_latent_cache'):
+            try:
+                cache = _latent_cache(request['reference_latent_cache'], request['base'], 'cuda')
+            except Exception:
+                cache = None
         conditions = [None, None]
         keys = []
         files = [keyframes['first'], keyframes['last']]
@@ -585,7 +589,7 @@ def attempt(index, failure):
                 width=width,
                 height=height,
                 frames=1,
-                crop_mode='put_on_canvas',
+                crop_mode='put_on_canvas_first' if idx == 0 else 'put_on_canvas_last',  # stretched vs cropped
                 base=request['base'],
                 device='cuda',
                 dtype='float32',

From fa94af262bd5e07002714422d216df0afec04b33 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 18:35:10 +0000
Subject: [PATCH 09/26] Kept-worker event names the roles still held and why
 others were given back

---
 freevideo_engine/comfy_nodes.py      |  6 +++++-
 freevideo_engine/resident_process.py | 19 +++++++++++++++++--
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/freevideo_engine/comfy_nodes.py b/freevideo_engine/comfy_nodes.py
index 9b9b59db..97331251 100644
--- a/freevideo_engine/comfy_nodes.py
+++ b/freevideo_engine/comfy_nodes.py
@@ -427,7 +427,11 @@ def busy():
             gpu = comfy_bridge.installation()[1].get('gpu_uuid')
         except (OSError, ValueError, KeyError, TypeError):
             gpu = None
-        kept = OWNER.finished(next_part=next_part, gpu=gpu, warm=True,
+        try:
+            admission = json.loads(output.with_suffix('.engine.json').read_text(encoding='utf-8')).get('resident_admission')
+        except (OSError, ValueError, AttributeError):
+            admission = None
+        kept = OWNER.finished(next_part=next_part, gpu=gpu, warm=True, decisions=admission,
                               agent=server is not None and str(getattr(server, 'client_id', '') or '').startswith('agent:'))
         from .comfy_environment import executor_device
         if target and not result_reused[0] and not executor_device():
diff --git a/freevideo_engine/resident_process.py b/freevideo_engine/resident_process.py
index 8337bdce..a6420fde 100644
--- a/freevideo_engine/resident_process.py
+++ b/freevideo_engine/resident_process.py
@@ -382,7 +382,7 @@ def take_decisions(self):
             rows, self.decisions = self.decisions, []
         return rows
 
-    def finished(self, *, next_part=None, agent=False, gpu=None, warm=False):
+    def finished(self, *, next_part=None, agent=False, gpu=None, warm=False, decisions=None):
         """Release the idle worker now, or keep it for the next request.
 
         A successful request (warm) keeps its settled caches above HOST_FLOOR while the card's use can be read, so
@@ -413,7 +413,8 @@ def finished(self, *, next_part=None, agent=False, gpu=None, warm=False):
             self.own = gpu_own(gpu) if warm else None
             threading.Thread(target=self._watch, args=(self.generation, self.idle_since, hold, gpu),
                              name='freevideo-resident-hold', daemon=True).start()
-            return self.record(action='kept', reason=next_part, seconds=hold, pid=self.process.pid)
+            return self.record(action='kept', reason=next_part, seconds=hold, pid=self.process.pid,
+                               **(held_summary(decisions) if decisions else {}))
 
     def _tight(self):
         from .system import windows
@@ -613,6 +614,20 @@ def close(self):
             self.process = None
 
 
+def held_summary(decisions):
+    """Roles the worker still holds after a request and why others were given back (fields for the kept event)."""
+    held, evicted = {}, []
+    for row in decisions if isinstance(decisions, list) else []:
+        if not isinstance(row, dict) or not isinstance(row.get('role'), str):
+            continue
+        if row.get('action') in ('admit', 'park', 'reuse', 'unpark'):
+            held[row['role']] = True
+        elif row.get('action') == 'evict':
+            held.pop(row['role'], None)
+            evicted.append({'role': row['role'], 'reason': str(row.get('reason') or '')[:120]})
+    return {'held': sorted(held), 'evicted': evicted}
+
+
 def gpu_used(gpu):
     try:
         from .background_room import Gpu

From f06cffedd650bf17d071bcd98076a0682162b5de Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 19:15:45 +0000
Subject: [PATCH 10/26] Trim agent tool descriptions and share more repeated
 schema shapes

Shorter parameter and tool descriptions, repeated shapes shared by reference only when the reference is shorter, and the tools/list size guard lowered to 185 KB. Idempotency, clamp and job-kind notes keep their full wording.
---
 freevideo_engine/agent/schema.py | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/freevideo_engine/agent/schema.py b/freevideo_engine/agent/schema.py
index f08e9be8..ecbef87a 100644
--- a/freevideo_engine/agent/schema.py
+++ b/freevideo_engine/agent/schema.py
@@ -120,12 +120,12 @@ def edit_recipe():
                           'then': {'required': ['from', 'to']}, 'else': {'required': ['width', 'height']}})
         operations.append(obj(props, ['op'] + required.get(name, []), **({'allOf': rules} if rules else {})))
     return obj({'operations': array({'oneOf': operations}, 1, MAX_OPERATIONS)}, ('operations',),
-               description='x-editor-recipe uses the shared CSS colour/ratio parsers. Source geometry and layer references also require editor preflight.',
+               description='Colours and ratios use CSS syntax; geometry and layer links are checked on submit.',
                **{'x-editor-recipe': True})
 
 
 def edit_document():
-    return {'type': 'object', 'required': ['version', 'layers'], 'properties': {'version': {'const': 2}}, 'description': 'Editor document version 2; x-editor-document uses the renderer pure document validator (geometry and layer relationships).',
+    return {'type': 'object', 'required': ['version', 'layers'], 'properties': {'version': {'const': 2}}, 'description': 'Editor document version 2.',
             'x-editor-document': True}
 
 
@@ -155,11 +155,11 @@ def media(image=False, *, local=False, clip=False, video=False, early=False):
             rules.append({'if': {'anyOf': [{'required': [k]} for k in ('from_job', 'library')]},
                           'then': {'required': ['frame']}})
     return {'oneOf': [FILE, obj(properties, allOf=rules)], 'x-media': dict(image=image, clip=clip, video=video),
-            'description': 'Exactly one source. x-media additionally checks clip end > start, a comparison JSON Schema cannot express.'}
+            'description': 'Exactly one source; end after start.' if clip else 'Exactly one source.'}
 
 
 def common():
-    return dict(label=string(120), project=SLUG, metadata={'x-json-bytes': 16 * 1024, 'description': 'x-json-bytes: serialized finite JSON of at most 16384 bytes.'},
+    return dict(label=string(120), project=SLUG, metadata={'x-json-bytes': 16 * 1024, 'description': 'Finite JSON, at most 16384 bytes.'},
                 after=array(JOB), ref=REF)
 
 
@@ -1604,7 +1604,7 @@ def openapi():
     description='Work session; omit for latest.')
 
 
-SHAPE_MIN_BYTES = 200
+SHAPE_MIN_BYTES = 60
 RECIPE_TOOL = 'freevideo_edit_image'
 
 
@@ -1663,9 +1663,10 @@ def rebuild(node, path):
         node = dict(node)
         for keyword, index, child in list(schema_children(node)):
             here, text = path + [(keyword, index)], key(child)
-            if counts.get(text, 0) > 1 and text in first:
-                child = dict({'type': child['type']} if 'type' in child else {},
-                             description='Same shape as %s.' % first[text])
+            named = text in first and dict({'type': child['type']} if 'type' in child else {},
+                                            description='Same as %s.' % first[text])
+            if named and len(json.dumps(named, ensure_ascii=False)) < len(json.dumps(child, ensure_ascii=False)):
+                child = named
             else:
                 if counts.get(text, 0) > 1:
                     first[text] = shape_label(here)

From ccc0a65f1ac9a92f408b83a11b95d691d1c3aad4 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 19:29:37 +0000
Subject: [PATCH 11/26] Editor: make a preview first and run its second pass in
 place; reusing settings keeps the seed

- The generation bar gets a menu beside Generate with the same Two-pass
choice as the creative panel (Off / On / Preview first). With Preview
first, a single part that continues nothing is generated as a
half-size preview and the button reads "Generate preview".
- A selected preview part that starts at the preview's first frame shows
"Run second pass" in the toolbar and the part menu. It continues the
preview's saved request and replaces the part in place, with the
generation bar's progress and cancel. Parts that continue an earlier
one or ranges planned as several parts always sample both passes.
- Saved works mark a finished preview from its saved request, so the
step is also offered after reopening.
- Reuse settings fills the original seed once; later generations follow
the seed setting as before.
---
 freevideo_engine/comfy_editor.py  |  12 ++++
 freevideo_engine/comfy_library.py |  21 ++++++-
 web/editor.css                    |   8 +++
 web/editor.js                     | 100 +++++++++++++++++++++++++++++-
 web/editor_entry.js               |  11 +++-
 web/editor_genbar.js              |  39 +++++++++++-
 web/editor_menu.js                |   4 ++
 web/editor_model.js               |  10 +++
 web/editor_tracks.css             |   5 ++
 web/health.js                     |   2 +-
 web/pass_mode.js                  |  39 ++++++++++++
 web/result_reuse.js               |   9 ++-
 web/studio.js                     |  56 ++++++++---------
 13 files changed, 273 insertions(+), 43 deletions(-)
 create mode 100644 web/pass_mode.js

diff --git a/freevideo_engine/comfy_editor.py b/freevideo_engine/comfy_editor.py
index a6925128..35d8ba04 100644
--- a/freevideo_engine/comfy_editor.py
+++ b/freevideo_engine/comfy_editor.py
@@ -742,6 +742,8 @@ def sources(root, keys):
                 text = _work_text(root, relative)
                 if text:
                     media['text'] = text
+            if source['kind'] in ('work', 'generated') and _is_preview(root, relative):
+                media['preview'] = True
             if source['kind'] == 'import':
                 metadata = _read_import(root, source['id'])
                 media.update(preview_width=media['width'], preview_height=media['height'])
@@ -771,6 +773,16 @@ def sources(root, keys):
     return result
 
 
+def _is_preview(root, relative):
+    """A finished first-pass preview whose second pass can be run from its saved request."""
+    try:
+        from .comfy_bridge import preview_request
+        preview_request(root, relative)
+        return True
+    except (ImportError, OSError, ValueError, TypeError):
+        return False
+
+
 def _work_text(root, relative):
     """The text a saved video was generated from; a block made from it starts with this description."""
     try:
diff --git a/freevideo_engine/comfy_library.py b/freevideo_engine/comfy_library.py
index 590ca999..a5188828 100644
--- a/freevideo_engine/comfy_library.py
+++ b/freevideo_engine/comfy_library.py
@@ -207,6 +207,23 @@ def prompt_text(output_directory, identity):
     return data.decode('utf-8').strip() if len(data) <= _PROMPT_BYTES else None
 
 
+def prompt_seed(output_directory, identity):
+    """The seed a saved video was generated with, or None (an export, an import, an old or damaged receipt)."""
+    path = _video(output_directory, identity)
+    root = Path(output_directory).resolve() / 'FreeVideo'
+    saved = path.with_name('comfy-request.json')
+    try:
+        if saved.is_symlink() or not saved.resolve().is_relative_to(root):
+            return None
+        with os.fdopen(os.open(saved, os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_BINARY', 0)), 'rb') as stream:
+            data = stream.read(4 * 1024**2 + 1)
+        state = json.loads(data) if len(data) <= 4 * 1024**2 else None
+    except (OSError, ValueError):
+        return None
+    seed = state.get('seed') if isinstance(state, dict) and state.get('status') == 'complete' else None
+    return seed if type(seed) is int and 0 <= seed < 2**64 else None
+
+
 def thumbnail(output_directory, identity):
     path = _video(output_directory, identity)
     saved = path.with_suffix('.thumbnail.jpg')
@@ -1238,7 +1255,9 @@ async def prompt(request):
             text = await asyncio.to_thread(prompt_text, folder_paths.get_output_directory(), request.query.get('id'))
         except (OSError, ValueError, UnicodeDecodeError):
             raise web.HTTPNotFound(text='Prompt unavailable') from None
-        return web.json_response(dict(prompt=text), headers={'Cache-Control': 'no-store'})
+        # The seed is optional: without it, reusing the settings fills only the prompt and the size.
+        seed = await asyncio.to_thread(prompt_seed, folder_paths.get_output_directory(), request.query.get('id'))
+        return web.json_response(dict(prompt=text, **({} if seed is None else {'seed': seed})), headers={'Cache-Control': 'no-store'})
 
     @server.routes.post('/freevideo/library/favorite')
     async def favorite(request):
diff --git a/web/editor.css b/web/editor.css
index 41d3bb69..576689e8 100644
--- a/web/editor.css
+++ b/web/editor.css
@@ -78,6 +78,14 @@
 .fv-ed-genbar[data-mode=running]>button:not(.fv-ed-generate){order:2}
 .fv-ed-gen-note{font-size:13px;color:var(--fv-ink);flex:0 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .fv-ed-gen-note[hidden]{display:none}
+.fv-ed-genbar .fv-ed-generate{flex:none;white-space:nowrap}
+.fv-ed-pass-options{position:relative;flex:none;margin-left:-8px}.fv-ed-pass-options[hidden]{display:none}
+.fv-ed-pass-options>summary{display:grid;place-items:center;width:32px;height:var(--fv-h);border:1px solid var(--fv-border);border-radius:var(--fv-r-sm);background:var(--fv-card);cursor:pointer;list-style:none}
+.fv-ed-pass-options>summary::-webkit-details-marker{display:none}
+.fv-ed-pass-options>summary:focus-visible{outline:2px solid var(--fv-accent);outline-offset:1px}
+.fv-editor .fv-ed-pass-options[open] .fv-chevron{transform:rotate(225deg)}
+.fv-ed-pass-menu{position:absolute;bottom:calc(100% + 10px);right:0;width:max-content;max-width:calc(100vw - 32px);padding:12px;border:1px solid var(--fv-border);border-radius:var(--fv-r-md);background:var(--fv-card);box-shadow:0 14px 45px #0006;animation:fv-preview-appear .16s ease;z-index:10}
+.fv-ed-pass-menu>strong{display:block;padding:0 2px 8px;font-size:var(--fv-micro);color:var(--fv-muted);font-weight:var(--fv-medium)}
 .fv-ed-gen-note:has(.fv-issue-button){white-space:normal;overflow:visible}
 .fv-ed-gen-note .fv-issue-button,.fv-ed-library-message .fv-issue-button{margin-left:8px}
 .fv-editor .fv-ed-gen-retry{height:auto;padding:0;border:0;background:none;color:inherit;font:inherit;cursor:pointer}
diff --git a/web/editor.js b/web/editor.js
index 97395550..f4dcfb1d 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -438,6 +438,12 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         return run;
     }
     const clipChoice = clips => ({kind: 'clip', ids: clips.flatMap(clip => clip.link ? [clip.id, clip.link] : [clip.id])});
+    // A part at range.start whose first frames come from the finished clip right before it.
+    function continuesEarlier(range) {
+        const head = state.record.tracks[0].clips.find(clip => clip.start === range.start);
+        return !!head && model.continuesBefore(state.record, head.id) && state.record.tracks[0].clips.some(clip =>
+            clip.start + clip.frames === range.start && clip.source && clip.extend && clip.in + clip.frames === clip.length);
+    }
     function busySelection(selection) {
         const range = selectionRange(selection); if (!range) return false;
         if ([...sendingRanges].some(other => overlaps(other, range))) return true;
@@ -934,6 +940,56 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 clip.start + clip.frames === range.start && clip.source && clip.extend && clip.in + clip.frames === clip.length);
             return before || model.rangeParts(state.record, {...range, ...capability}).length > 1;
         },
+        // The creative panel's two-pass choices as this edit uses them: the edit's own two-pass setting decides
+        // off or on, and the panel's "Preview first" applies when it samples twice. Null without an open panel.
+        passMode() {
+            const shared = panel.passMode; if (!shared) return null;
+            const value = shared.state(), twoPass = state.record.settings?.two_pass ?? value.mode !== 'off';
+            return {...value, mode: !twoPass ? 'off' : value.mode === 'off' ? 'on' : value.mode};
+        },
+        // One choice for both places: the panel takes it, and the edit takes the sampling settings it leaves.
+        choosePass(mode) {
+            const shared = panel.passMode; if (!shared) return;
+            shared.choose(mode);
+            const now = panel.sampling?.() || {}, set = state.record.settings || {};
+            if (Object.entries(now).some(([key, value]) => set[key] !== value)) state.settle(record => model.setSampling(record, now));
+            else genbar?.update(mostRecentJob ? jobStatuses.get(mostRecentJob) ?? null : null);
+        },
+        onPass: listener => panel.passMode?.subscribe(listener) || (() => {}),
+        // A part made as a half-resolution preview: only one that stands alone, as the next part continues from
+        // this one's last frames, which the second pass changes.
+        previewFirst(selection = state.selection) {
+            if (actions.passMode()?.mode !== 'preview' || music.target(selection)) return false;
+            if ((state.record.settings?.base_steps ?? 8) !== 8) return false;
+            const run = partRun(selection), chosen = run ? clipChoice(run) : selection, range = selectionRange(chosen); if (!range) return false;
+            if (continuesEarlier(range)) return false;
+            try {
+                // The parts Generate would send, planned as it plans them.
+                const selected = selectionClips(chosen), planned = selected.length && selected.every(clip => clip.pending && !clip.source);
+                const next = planned ? state.record : model.planRange(state.record, {...range, target: 'both', maxSeconds: capability.maxSeconds, maxFollowSeconds: capability.maxFollowSeconds});
+                const ids = planned ? selected.map(clip => clip.id) : next.tracks[0].clips.filter(clip => clip.start >= range.start && clip.start < range.start + range.frames
+                    && clip.pending && !['queued', 'running'].includes(clip.pending)).map(clip => clip.id);
+                return ids.length === 1 && !model.generationBefore(model.prepare(next, ids), ids).some(Boolean);
+            } catch (value) { if (value instanceof model.EditError) return false; throw value; }
+        },
+        // The chosen preview part, shown from its first frame, whose second pass can replace it in place.
+        secondPassTarget(selection = state.selection) {
+            if (selection?.kind !== 'clip' || !store.generationAvailable) return null;
+            const clips = selectionClips(selection);
+            if (clips.length !== 1) return null;
+            const clip = clips[0], mate = clip.link ? model.find(state.record, clip.link) : null;
+            // From the start of the preview: the second pass makes the same frames again, so a part cut short at its end still shows the same moment.
+            if (!clip.source || clip.pending || mate?.pending || clip.in !== 0 || clip.frames > clip.length) return null;
+            const metadata = store.sources.get(sourceKey(clip.source));
+            return metadata?.preview === true && metadata.path ? {clip, path: metadata.path} : null;
+        },
+        generationSending: () => generationBusy,
+        async secondPass(selection = state.selection) {
+            const found = actions.secondPassTarget(selection); if (!found) return;
+            const choice = clipChoice([found.clip]);
+            await actions.generate({text: found.clip.text || '', selection: choice, shown: selection === state.selection,
+                label: t('Run second pass', '继续二采'), secondPass: found.path, allowEmpty: true});
+        },
         // Pictures that guide a new part: the creative panel's media rows; a part that continues shows only its references.
         references: panel.references ? {source: panel.references, notify, size: () => capability.generationSize || generationSize(state.record),
             visible: () => store.generationAvailable && actions.supportedSelection() ? partStart() : null} : null,
@@ -953,13 +1009,15 @@ export function openEditor({api, app, from = null, panel = {}, components: given
             return seconds;
         },
         // texts: a description for each planned part, by the part's picture; otherwise text is every part's.
-        async generate({target = 'both', text = '', texts = null, label = t('Generate', '生成'), selection = state.selection, shown = selection === state.selection, allowEmpty = false} = {}) {
+        // secondPass: the preview video whose second pass replaces it; the engine continues that preview's own request.
+        async generate({target = 'both', text = '', texts = null, label = t('Generate', '生成'), selection = state.selection, shown = selection === state.selection, allowEmpty = false, secondPass = null} = {}) {
             if (target !== 'both' || !actions.supportedSelection(selection)) throw new model.EditError('unsupported');
             // A half of a pair left by a cut or a paste is dropped; a description over the limit is said before anything is sent.
             text = wellFormed(text);
             // Only the user's own choice to go on without a description lets an empty one through.
             if (!(allowEmpty === true && !text.trim() && store.generationAvailable && actions.needsText(selection)) && !actions.canGenerate(text, selection)) throw new model.EditError('text');
             if (characters(text) > model.RULES.maxText) throw Object.assign(new model.EditError('text_long'), {limit: model.RULES.maxText});
+            const previewing = !secondPass && actions.previewFirst(selection);
             submissionFailure = null; genbar?.update(null);
             const chosen = state.selection;
             generationBusy = true; updateTop(); updateTransport();
@@ -1009,6 +1067,15 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 }
                 const follow = continuedSize(beforeKeys, sizes), edit = capability.generationSize || generationSize(state.record);
                 Object.assign(frozen.prompt[frozen.node].inputs, follow || {});
+                // A preview is one part that continues nothing; any other part samples both passes, whatever the panel shows.
+                const inputs = frozen.prompt[frozen.node].inputs, alone = request.blocks.length === 1 && !beforeKeys.some(Boolean);
+                if (secondPass) {
+                    if (!alone) throw new model.EditError('unsupported');
+                    Object.assign(inputs, {two_pass: true, preview: false, refine_from: secondPass});
+                } else {
+                    if ('preview' in inputs || previewing) inputs.preview = previewing && alone;
+                    if ('refine_from' in inputs) inputs.refine_from = '';
+                }
                 if (allowEmpty === true && [text, ...Object.values(texts ?? {})].some(value => !value.trim())) allowEmptyPrompt({output: frozen.prompt}, frozen.node);
                 // Parts made at another size than the edit's have that size's limit.
                 const limit = (follow && (follow.width !== edit.width || follow.height !== edit.height)
@@ -1310,13 +1377,38 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         const clip = selectedContent().find(clip => clip.versions.length);
         if (clip) try { state.apply(t('Previous version', '上一版'), record => model.restoreVersion(record, clip.id, 0)); } catch (value) { error(value, null, undefined, 'restore'); }
     }, 'fv-ed-previous');
+    // A whole preview part continues to its full-resolution video in place; any other part shows nothing here.
+    const secondPassButton = toolButton(t('Run second pass', '继续二采'), 'M9.5 2.5h4v4M13.5 2.5 9 7M6.5 13.5h-4v-4M2.5 13.5 7 9',
+        () => { void runSecondPass(); }, 'fv-ed-second-pass');
+    const secondPassLabel = el('span', 'fv-ed-second-pass-label');
+    secondPassButton.classList.remove('fv-ed-icon'); secondPassButton.append(secondPassLabel); secondPassButton.hidden = true;
+    let secondPassFailed = null;
+    function updateSecondPass() {
+        const found = actions.secondPassTarget();
+        secondPassButton.hidden = !found;
+        if (!found) { secondPassFailed = null; return; }
+        if (secondPassFailed !== found.clip.id) secondPassFailed = null;
+        const words = secondPassFailed ? t('Second pass did not start · retry', '二采没有开始 · 重试') : t('Run second pass', '继续二采');
+        secondPassLabel.textContent = words; secondPassButton.setAttribute('aria-label', words); secondPassButton.title = words;
+        secondPassButton.disabled = generationBusy;
+    }
+    async function runSecondPass(selection = state.selection) {
+        const found = actions.secondPassTarget(selection);
+        if (!found || generationBusy) return;
+        secondPassFailed = null;
+        try { await actions.secondPass(selection); }
+        catch (value) { if (!disposed) { secondPassFailed = found.clip.id; error(value); } }
+        finally { if (!disposed) updateSecondPass(); }
+    }
+    actions.runSecondPass = runSecondPass;
     historyTools.append(toolUndo, toolRedo); editTools.append(split, remove, closeGap, previous);
     const pictureTools = createPictureTools({state, sources: store.sources, t, capabilities: () => capability, error});
     toolbar.append(historyTools, editTools, zoomHost); element.insertBefore(toolbar, tracksHost);
     const transportControls = createEditorTransport({element, preview, transport, toolbar, editTools, zoomHost, state, player, t, notify});
+    editTools.append(secondPassButton);
     toolbar.append(adjust.toggleButton);
     const textTools = createEditorText({element, state, t, actions, adjust, player, toolbar, exportBox, tracksHost});
-    const toolbarMore = createToolbarMore({toolbar, t, keep: '.fv-ed-undo, .fv-ed-split, .fv-ed-delete, .fv-ed-adjust-toggle, .fv-ed-zoom, .fv-ed-stems-button'});
+    const toolbarMore = createToolbarMore({toolbar, t, keep: '.fv-ed-undo, .fv-ed-split, .fv-ed-delete, .fv-ed-adjust-toggle, .fv-ed-zoom, .fv-ed-stems-button, .fv-ed-second-pass'});
     actions.speech.ability().then(value => { if (!disposed) textTools.speech(value); }).catch(() => {});
     const audio = createAudioIntegration({state, player, t, error, adjust, library: libraryHost, store});
     stems = createStemsIntegration({state, api, queue, store, t, error, notify, toolbar, show: job => genbar?.update(job),
@@ -1365,10 +1457,11 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         const multiple = isMultiple(state.record, clips.map(clip => clip.id));
         previous.disabled = busy || multiple || !clips.some(clip => clip.versions.length);
         previous.title = t('Previous version', '上一版');
+        updateSecondPass();
         updateZoom();
     }
     updateTransport();
-    const stopSources = store.subscribeSources(() => { player.refresh(); tracks?.refresh?.(); pictureTools.update(); updateTop(); });
+    const stopSources = store.subscribeSources(() => { player.refresh(); tracks?.refresh?.(); pictureTools.update(); updateTop(); updateSecondPass(); });
     let capabilitySize = `${state.record.width}x${state.record.height}`;
     // The reason, said as soon as the selected continuation follows a video that already has the most parts, once per selection.
     let hintedFor = '';
@@ -1411,6 +1504,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         if (pictureEdit.keyboard(event)) return true;
         if (adjust.dismiss(event)) return true;
         if (toolbarMore.dismiss(event)) return true;
+        if (genbar?.dismiss(event)) return true;
         if (menu.hidden) return false;
         event.preventDefault(); event.stopPropagation();
         if (!menu.hidden) { menu.hidden = true; title.setAttribute('aria-expanded', 'false'); title.focus(); }
diff --git a/web/editor_entry.js b/web/editor_entry.js
index 2d10a55e..a139cdfc 100644
--- a/web/editor_entry.js
+++ b/web/editor_entry.js
@@ -8,10 +8,19 @@ import {openAutopilot, viewChanged} from './view_navigation.js';
 import {mediaReferences} from './editor_media_references.js';
 import {turnNodeOn} from './studio_queue.js';
 function editorPanel(node) {
-    const values = Object.fromEntries((node.widgets || []).filter(widget => widget.name).map(widget => [widget.name, widget.value]));
+    const read = () => Object.fromEntries((node.widgets || []).filter(widget => widget.name).map(widget => [widget.name, widget.value]));
+    const values = read();
     return {node: node.id, width: values.width, height: values.height, text: values.text || '', settings: Object.fromEntries(Object.entries({
         two_pass: values.two_pass, base_steps: values.base_steps, refine_steps: values.refine_steps,
         step_cache: values.step_cache, upscale_factor: values.upscale_factor, seed: values.seed, sampling_effort: values.sampling_effort}).filter(([, value]) => value !== undefined)),
+        // The creative panel's two-pass choices, which the generation bar shows too; null without an open panel.
+        get passMode() { return node.freevideoPassMode || null; },
+        // What a two-pass choice leaves in the panel's sampling settings now.
+        sampling() {
+            const now = read();
+            return Object.fromEntries(Object.entries({two_pass: now.two_pass, base_steps: now.base_steps, refine_steps: now.refine_steps,
+                step_cache: now.step_cache, upscale_factor: now.upscale_factor}).filter(([, value]) => value !== undefined));
+        },
         references: mediaReferences(node),
         async snapshot() {
             if (node.freevideoEditorLooping?.()) throw new Error('loop_active');
diff --git a/web/editor_genbar.js b/web/editor_genbar.js
index c8183c06..5bb35ff9 100644
--- a/web/editor_genbar.js
+++ b/web/editor_genbar.js
@@ -8,6 +8,7 @@ import {issueButton} from './issue_button.js';
 import {waitingText} from './chain_support.js';
 import {showEmptyPrompt} from './empty_prompt_notice.js';
 import {segmented} from './editor_adjust.js';
+import {createPassMode} from './pass_mode.js';
 const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
 export const timeEstimate = (seconds, t) => seconds == null ? '' : seconds < 60
     ? t(`about ${Math.max(1, Math.ceil(seconds))} s`, `约 ${Math.max(1, Math.ceil(seconds))} 秒`)
@@ -53,6 +54,20 @@ export function createEditorGenbar(host, {state, t, actions, text = ''}) {
     input.dataset.fvGuide = 'editor-describe'; generate.dataset.fvGuide = 'editor-generate';
     for (const button of [generate, cancel, resume]) button.type = 'button';
     host.append(hint, note, description, generate, cancel, resume);
+    // Beside Generate, as beside the creative panel's Generate video: the panel's own two-pass choices, the same setting.
+    const passMenu = actions.passMode ? el('details', 'fv-ed-pass-options') : null;
+    // The editor routes keys itself and calls a control's onkeydown, as for the toolbar's ⋯ panel.
+    const routed = (target, type, handler) => { target.onkeydown = handler; return () => { target.onkeydown = null; }; };
+    const passControl = passMenu ? createPassMode({t, onChoose: mode => { actions.choosePass(mode); render(); }, listen: routed}) : null;
+    let stopPass = null;
+    if (passMenu) {
+        const toggle = el('summary'); toggle.setAttribute('aria-label', t('Two-pass', '二次采样')); toggle.append(el('span', 'fv-chevron'));
+        const panel = el('div', 'fv-ed-pass-menu'); panel.append(el('strong', null, t('Two-pass', '二次采样')), passControl.element);
+        passMenu.append(toggle, panel); passMenu.hidden = true; generate.after(passMenu);
+        stopPass = actions.onPass?.(() => render()) || null;
+    }
+    const closePass = event => { if (passMenu?.open && !passMenu.contains(event.target)) passMenu.open = false; };
+    document.addEventListener('pointerdown', closePass, true);
     // The line's own "check again", shown whenever nothing else is said there.
     const retryService = el('button', 'fv-ed-gen-retry', t('Generation unavailable · retry', '生成服务暂不可用 · 重试')); retryService.type = 'button';
     let service = null;
@@ -223,8 +238,20 @@ export function createEditorGenbar(host, {state, t, actions, text = ''}) {
         // A piece already made, failed or stopped is made again in place; separated music is replaced in place.
         const aimed = musical ? music.target(selection) : null;
         const made = !!aimed?.clip && aimed.clip.pending !== 'draft';
-        const verb = aimed?.replace ? t('Replace music', '替换配乐') : made ? t('Regenerate', '重新生成') : t('Generate', '生成');
+        // "Preview first" names the press after what it makes; a part already made is made again as a preview.
+        const previewing = !musical && !!actions.previewFirst?.(selection);
+        const remade = previewing && selection?.kind === 'clip' && state.record.tracks[0].clips.some(clip =>
+            (selection.ids.includes(clip.id) || selection.ids.includes(clip.link)) && clip.source);
+        const verb = aimed?.replace ? t('Replace music', '替换配乐') : made ? t('Regenerate', '重新生成')
+            : remade ? t('Regenerate preview', '重新生成预览') : previewing ? t('Generate preview', '生成预览') : t('Generate', '生成');
         generate.textContent = verb;
+        if (passMenu) {
+            const pass = actions.passMode();
+            // While a part generates, the bar shows its progress and Cancel; the choice waits for the next press.
+            passMenu.hidden = !pass || musical || generate.hidden || busy;
+            if (pass) passControl.sync(pass);
+            if (passMenu.hidden) passMenu.open = false;
+        }
         // Never disabled for a reason the press itself can explain or fix; only until the server says it can generate.
         generate.disabled = busy || !!previewSelection || !!actions.generationWaiting?.();
         resizeDescription();
@@ -329,13 +356,19 @@ export function createEditorGenbar(host, {state, t, actions, text = ''}) {
         if (event.type === 'selection' || event.type === 'record') render();
     });
     render();
-    return {element: host, say, downloadFailure, commit,
+    // Escape arrives through the editor's popup chain: an open two-pass menu closes first.
+    function dismiss(event) {
+        if (!passMenu?.open) return false;
+        event.preventDefault(); event.stopPropagation(); passMenu.open = false; passMenu.querySelector('summary').focus();
+        return true;
+    }
+    return {element: host, say, downloadFailure, commit, dismiss,
         service(value) {
             service = value;
             if (!value && note.contains(retryService)) { retryService.remove(); note.hidden = true; }
             showService();
         }, getText() { expand.commit(); return input.value; }, update(value) { status = value; render(); }, preview(selection) { previewSelection = selection; render(); }, setText(value) { input.value = value || ''; state.setRangeText(input.value); if (bound && input.value !== bound.text) { dirty = true; written = input.value; } render(); },
-        dispose() { disposed = true; ++serial; clearTimeout(noteTimer); clearTimeout(refNoticeTimer); duration.dispose(); unsubscribe(); resize?.disconnect(); expand.dispose(); references?.dispose(); assets?.dispose(); Object.values(pickers).forEach(picker => picker.dispose()); }};
+        dispose() { disposed = true; ++serial; clearTimeout(noteTimer); stopPass?.(); passControl?.dispose(); document.removeEventListener('pointerdown', closePass, true); clearTimeout(refNoticeTimer); duration.dispose(); unsubscribe(); resize?.disconnect(); expand.dispose(); references?.dispose(); assets?.dispose(); Object.values(pickers).forEach(picker => picker.dispose()); }};
 }
 
 // A missing optional module leaves the editor's existing progress in place.
diff --git a/web/editor_menu.js b/web/editor_menu.js
index eff3e1b2..6fadae25 100644
--- a/web/editor_menu.js
+++ b/web/editor_menu.js
@@ -46,6 +46,10 @@ export function menuItems(context) {
         command('v', t('Paste', '粘贴'), `${modifier}+V`, commands.canPaste()),
         command('a', t('Select all', '全选'), `${modifier}+A`, record.tracks.some(track => track.clips.length)),
     ];
+    // Only a whole preview part offers its second pass; it replaces the part in place.
+    const preview = context.where === 'part' && context.actions.secondPassTarget?.(context.state.selection);
+    if (preview && context.actions.runSecondPass) items.push({group: 'generate', label: t('Run second pass', '继续二采'), shortcut: '',
+        enabled: !context.actions.generationSending?.(), run: () => context.actions.runSecondPass(context.state.selection)});
     const value = field => typeof field === 'function' ? field(context) : field;
     for (const item of registered) if (item.where === context.where) items.push({...item,
         label: value(item.label), shortcut: value(item.shortcut) || '', enabled: item.enabled ? !!item.enabled(context) : true,
diff --git a/web/editor_model.js b/web/editor_model.js
index a18497ad..d4a70d8e 100644
--- a/web/editor_model.js
+++ b/web/editor_model.js
@@ -110,6 +110,16 @@ export function setFlag(record, key, value) {
     if (JSON.stringify(next.settings) !== JSON.stringify(record.settings)) next.keep_empty = true;
     return parse(next);
 }
+// The sampling settings a two-pass choice sets, copied from the creative panel so this edit makes its parts the same way.
+const SAMPLING_KEYS = ['two_pass', 'base_steps', 'refine_steps', 'step_cache', 'upscale_factor'];
+export function setSampling(record, values) {
+    check(object(values) && Object.entries(values).every(([key, value]) => SAMPLING_KEYS.includes(key)
+        && ['boolean', 'number', 'string'].includes(typeof value)), 'settings');
+    const next = serialize(record), settings = {...(next.settings || {}), ...values};
+    next.settings = settings;
+    if (JSON.stringify(next.settings) !== JSON.stringify(record.settings)) next.keep_empty = true;
+    return parse(next);
+}
 export function addAudioTrack(record) {
     const next = serialize(record);
     check(!next.tracks.some(track => track.id === 'a2'), 'track');
diff --git a/web/editor_tracks.css b/web/editor_tracks.css
index bd5929ac..c222421d 100644
--- a/web/editor_tracks.css
+++ b/web/editor_tracks.css
@@ -112,5 +112,10 @@
 .fv-editor .fv-ed-toolbar .fv-ed-stems-button[hidden]{display:none}
 .fv-editor .fv-ed-toolbar .fv-ed-stems-button .fv-ed-glyph{width:16px;height:16px;flex:none}
 @media(max-width:520px){.fv-editor .fv-ed-toolbar .fv-ed-stems-button{width:32px;padding:0}.fv-ed-stems-label{display:none}}
+.fv-editor .fv-ed-toolbar .fv-ed-second-pass{width:auto;padding:0 10px;background:var(--fv-accent);border-color:var(--fv-accent);color:var(--fv-bg);font-weight:var(--fv-semibold)}
+.fv-editor .fv-ed-toolbar .fv-ed-second-pass:not(:disabled):hover{background:var(--fv-accent-hover);border-color:var(--fv-accent-hover)}
+.fv-editor .fv-ed-toolbar .fv-ed-second-pass[hidden]{display:none}
+.fv-editor .fv-ed-toolbar .fv-ed-second-pass svg{width:16px;height:16px;flex:none}
+@media(max-width:520px){.fv-editor .fv-ed-toolbar .fv-ed-second-pass{width:32px;padding:0}.fv-ed-second-pass-label{display:none}}
 .fv-editor .fv-ed-toolbar .fv-ed-stems-group{margin-left:-8px}.fv-editor .fv-ed-toolbar .fv-ed-stems-group:before{display:none}.fv-ed-stems-group[hidden]{display:none}
 @media(max-width:480px){.fv-editor .fv-ed-toolbar .fv-ed-stems-group{margin-left:0}}
diff --git a/web/health.js b/web/health.js
index 7abb15fd..3a99a77c 100644
--- a/web/health.js
+++ b/web/health.js
@@ -17,7 +17,7 @@ export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', '
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_stems.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'image_lora.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
-    'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
+    'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'pass_mode.js','setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
     'toolbar_position.js', 'updates.js', 'view_navigation.js', 'wordmark.js', 'workspace_restore.js', 'cast_library.js', 'media_upload.js', 'whitebox_encode.js', 'whitebox_mp4.js', 'whitebox_recording.js', 'whitebox_render.js', 'whitebox_scenes.js', 'whitebox_worker.js',
     'empty_prompt_notice.js', 'feature_tour.js', 'feature_tour_content.js', 'howto.js', 'swap_lora.js', 'tour_try.js', 'tutorial_book.js', 'tutorial_book_content.js'];
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
diff --git a/web/pass_mode.js b/web/pass_mode.js
new file mode 100644
index 00000000..29a65f92
--- /dev/null
+++ b/web/pass_mode.js
@@ -0,0 +1,39 @@
+// Two-pass sampling as three choices: off, on, or on and paused after a half-resolution first pass.
+// The creative panel and the editor's generation bar show this one control over the same node settings.
+const plainListen = (target, type, handler) => {
+    target.addEventListener(type, handler);
+    return () => target.removeEventListener(type, handler);
+};
+
+export function createPassMode({t, onChoose, listen = plainListen}) {
+    const element = document.createElement('div');
+    element.className = 'fv-pass-mode'; element.setAttribute('role', 'radiogroup');
+    element.setAttribute('aria-label', t('Two-pass sampling', '二次采样'));
+    const options = [['off', t('Off', '关闭')], ['on', t('On', '开启')], ['preview', t('Preview first', '先出预览')]].map(([mode, label]) => {
+        const option = document.createElement('button');
+        option.type = 'button'; option.textContent = label; option.dataset.mode = mode; option.setAttribute('role', 'radio');
+        option.onclick = () => onChoose(mode);
+        return option;
+    });
+    element.append(...options);
+    const stop = listen(element, 'keydown', event => {
+        const step = {ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1}[event.key];
+        if (!step) return;
+        event.preventDefault();
+        const enabled = options.filter(option => !option.disabled && !option.hidden);
+        const current = enabled.findIndex(option => option.getAttribute('aria-checked') === 'true');
+        const next = enabled[(current + step + enabled.length) % enabled.length];
+        if (next) { next.click(); next.focus(); }
+    });
+    // state: {mode, disabled: {off, on, preview}, hidden: {preview}, hint}; the hint is the preview choice's title.
+    function sync(state) {
+        for (const option of options) {
+            const key = option.dataset.mode, selected = key === state.mode;
+            option.setAttribute('aria-checked', String(selected)); option.tabIndex = selected ? 0 : -1;
+            option.disabled = Boolean(state.disabled?.[key]);
+            option.hidden = Boolean(state.hidden?.[key]);
+            option.title = key === 'preview' ? state.hint || '' : '';
+        }
+    }
+    return {element, options, sync, dispose: stop};
+}
diff --git a/web/result_reuse.js b/web/result_reuse.js
index d255802b..5e743457 100644
--- a/web/result_reuse.js
+++ b/web/result_reuse.js
@@ -14,17 +14,20 @@ export async function savedSettings(api, record) {
     try {
         const reply = await api.fetchApi('/freevideo/library/prompt?' + new URLSearchParams({id}), {cache: 'no-store'});
         if (!reply.ok) return null;
-        const {prompt} = await reply.json();
+        const {prompt, seed} = await reply.json();
         if (typeof prompt !== 'string' || !prompt) return null;
         // The panel keeps seconds to three decimals, so the frames it will ask for are those of that rounded duration.
         const raw = Number(g.frames) > 0 ? Number(g.frames) / 24 : Number(g.seconds);
         const seconds = raw > 0 ? Math.floor(raw * 1000) / 1000 : null;
-        return {text: prompt, width: Number(g.width), height: Number(g.height), seconds, frames: seconds === null ? null : framesOf(seconds)};
+        // The seed comes back once, so the same prompt and size make the same video; an older video kept none.
+        return {text: prompt, width: Number(g.width), height: Number(g.height), seconds, frames: seconds === null ? null : framesOf(seconds),
+            seed: Number.isSafeInteger(seed) && seed >= 0 ? seed : null};
     } catch { return null; }
 }
 
 // Whether filling the saved settings would change anything the panel can still change.
 export function differs(saved, now) {
     return saved.text !== now.text || saved.width !== now.width || saved.height !== now.height
-        || (saved.frames !== null && saved.frames !== now.frames);
+        || (saved.frames !== null && saved.frames !== now.frames)
+        || (saved.seed != null && now.seed != null && saved.seed !== now.seed);
 }
diff --git a/web/studio.js b/web/studio.js
index 59e20751..df61d749 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -56,6 +56,7 @@ import { activeOriginal, checkOriginal, lockMark, blockOriginal, originalBlocked
 import { waitingText } from './chain_support.js';
 import { createExtendState, extendText, extendSourceProblem, extendSourceState, readExtendRecord, extendSnapshot, mountExtendThumbnail, videoUnavailableText } from './studio_extend.js';
 import { topDialog, isolateDialogKeys, listenDialogKey, routeDialogKey } from './dialog_keys.js';
+import { createPassMode } from './pass_mode.js';
 
 const languageOverride = typeof location !== 'undefined'
     ? new URLSearchParams(location.search).get('freevideo_lang') : null;
@@ -910,26 +911,11 @@ export function openStudio(node, {extendFrom = null} = {}) {
     twoPassLabel.title = t('Generates at a lower resolution, then upscales. Faster.', '先用低分辨率生成，再放大成片，更快。');
     const twoPassStatus = el('small', '', 'fv-two-pass-status');
     // Off, on, or on and paused after the first pass: a preview is one way to run two-pass.
-    const passMode = el('div', null, 'fv-pass-mode'); passMode.setAttribute('role', 'radiogroup');
-    passMode.setAttribute('aria-label', t('Two-pass sampling', '二次采样'));
-    const passOptions = [['off', t('Off', '关闭')], ['on', t('On', '开启')], ['preview', t('Preview first', '先出预览')]].map(([mode, label]) => {
-        const option = el('button', label); option.type = 'button'; option.dataset.mode = mode; option.setAttribute('role', 'radio');
-        option.onclick = () => choosePassMode(mode);
-        return option;
-    });
-    passOptions[2].title = t('Stops at a half-resolution preview. Choose "Run second pass" in the result when it looks right; the video matches a direct run.',
+    const passControl = createPassMode({t, onChoose: mode => choosePassMode(mode), listen: listenDialogKey});
+    const passMode = passControl.element;
+    cleanup.push(passControl.dispose);
+    const previewPassHint = t('Stops at a half-resolution preview. Choose "Run second pass" in the result when it looks right; the video matches a direct run.',
         '先出半分辨率预览，满意后在结果里点“继续二采”，成片与直接生成一致。');
-    const previewPassHint = passOptions[2].title;
-    passMode.append(...passOptions);
-    cleanup.push(listenDialogKey(passMode, 'keydown', event => {
-        const step = {ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1}[event.key];
-        if (!step) return;
-        event.preventDefault();
-        const enabled = passOptions.filter(option => !option.disabled && !option.hidden);
-        const current = enabled.findIndex(option => option.getAttribute('aria-checked') === 'true');
-        const next = enabled[(current + step + enabled.length) % enabled.length];
-        if (next) { next.click(); next.focus(); }
-    }));
     twoPassLabel.append(el('span', t('Two-pass', '二次采样')), twoPassStatus, passMode);
     let effortEstimate = {}, effortEstimateKey = '', effortEstimateTimer = null, effortEstimateRequest = null, lengthControl = null, chainController = null;
     // A level's step cache; custom steps and workflows without the input sample every step.
@@ -966,19 +952,24 @@ export function openStudio(node, {extendFrom = null} = {}) {
         if (previewFirst.checked !== wantsPreview) { previewFirst.checked = wantsPreview; set(node, 'preview', wantsPreview); }
         syncSamplingSteps(); updateRunButton();
     }
-    function syncPassMode() {
-        const mode = !twoPass.checked ? 'off' : previewFirst.checked ? 'preview' : 'on';
+    function passState() {
         const passLinked = linked(node, 'two_pass'), previewLinked = linked(node, 'preview');
-        for (const option of passOptions) {
-            const selected = option.dataset.mode === mode;
-            option.setAttribute('aria-checked', String(selected)); option.tabIndex = selected ? 0 : -1;
-            option.title = !(passLinked || (option.dataset.mode === 'preview' && previewLinked)) && option.dataset.mode === 'preview' ? previewPassHint : '';
-        }
-        passOptions[0].disabled = Boolean(extension.source) || passLinked || !widget(node, 'two_pass');
-        passOptions[1].disabled = twoPass.disabled;
-        passOptions[2].disabled = Boolean(extension.source) || twoPass.disabled || previewLinked || !widget(node, 'preview');
-        passOptions[2].hidden = !widget(node, 'preview');
+        return {mode: !twoPass.checked ? 'off' : previewFirst.checked ? 'preview' : 'on',
+            disabled: {off: Boolean(extension.source) || passLinked || !widget(node, 'two_pass'), on: twoPass.disabled,
+                preview: Boolean(extension.source) || twoPass.disabled || previewLinked || !widget(node, 'preview')},
+            hidden: {preview: !widget(node, 'preview')}, hint: passLinked || previewLinked ? '' : previewPassHint};
     }
+    // The editor's generation bar shows the same choices; it hears every change made here and chooses through here.
+    const passListeners = new Set();
+    function syncPassMode() {
+        const value = passState();
+        passControl.sync(value);
+        for (const listener of [...passListeners]) listener(value);
+    }
+    const sharedPass = {state: passState, choose: mode => choosePassMode(mode),
+        subscribe(listener) { passListeners.add(listener); return () => passListeners.delete(listener); }};
+    node.freevideoPassMode = sharedPass;
+    cleanup.push(() => { passListeners.clear(); if (node.freevideoPassMode === sharedPass) delete node.freevideoPassMode; });
     samplingSettings.append(effort.element, twoPassLabel);
     canvas.append(samplingSettings); cleanup.push(() => effort.dispose());
     cleanup.push(() => { clearTimeout(effortEstimateTimer); effortEstimateRequest?.abort(); });
@@ -1467,7 +1458,8 @@ export function openStudio(node, {extendFrom = null} = {}) {
             const sizeLocked = dimensionsLinked || Boolean(extension.source), lengthLocked = linked(node, 'seconds') || Boolean(extension.source);
             return {text: prompt.disabled ? saved.text : requestText(prompt.value, node.properties?.freevideo_prompt_versions), width: sizeLocked ? saved.width : Number(value(node, 'width')),
                 height: sizeLocked ? saved.height : Number(value(node, 'height')),
-                frames: lengthLocked ? saved.frames : framesOf(seconds.value), seconds: Number(seconds.value)};
+                frames: lengthLocked ? saved.frames : framesOf(seconds.value), seconds: Number(seconds.value),
+                seed: linked(node, 'seed') || !widget(node, 'seed') ? saved.seed ?? null : Number(value(node, 'seed'))};
         },
         apply: saved => {
             reuseApplying = true;
@@ -1478,6 +1470,8 @@ export function openStudio(node, {extendFrom = null} = {}) {
                     seconds.value = String(saved.seconds);
                     seconds.dispatchEvent(new Event('input')); seconds.dispatchEvent(new Event('change'));
                 }
+                // The next run uses this seed; after it, the panel's own "after generating" choice moves it as usual.
+                if (saved.seed != null && !linked(node, 'seed') && widget(node, 'seed')) { set(node, 'seed', saved.seed); seed.value = String(saved.seed); }
             } finally { reuseApplying = false; }
         },
         onEdit: listener => {

From d86afdc6dd636739d132fcb631d8dfdefca9f04f Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 19:53:38 +0000
Subject: [PATCH 12/26] Page check lists the other-program usage notice script

---
 web/health.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/health.js b/web/health.js
index 3a99a77c..a7586387 100644
--- a/web/health.js
+++ b/web/health.js
@@ -17,7 +17,7 @@ export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', '
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_stems.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'image_lora.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
-    'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'pass_mode.js','setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
+    'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'pass_mode.js','setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'other_usage.js', 'studio_queue.js', 'studio_size.js',
     'toolbar_position.js', 'updates.js', 'view_navigation.js', 'wordmark.js', 'workspace_restore.js', 'cast_library.js', 'media_upload.js', 'whitebox_encode.js', 'whitebox_mp4.js', 'whitebox_recording.js', 'whitebox_render.js', 'whitebox_scenes.js', 'whitebox_worker.js',
     'empty_prompt_notice.js', 'feature_tour.js', 'feature_tour_content.js', 'howto.js', 'swap_lora.js', 'tour_try.js', 'tutorial_book.js', 'tutorial_book_content.js'];
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

From b8359e2f67c4f47d0ee8a7756f9275e4859fd295 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 20:02:38 +0000
Subject: [PATCH 13/26] Editor: ripple delete removes a clip and closes the
 time it took

- Shift+Delete / Shift+Backspace and a part menu entry right below Delete remove the selected clips and move later content on every track earlier by the time they took. A gap that was already there stays. One undo restores both.
- When the content after a clip cannot move earlier (it would overlap, sits on a locked track or is generating), the clip is still deleted, the gap remains and the editor says so.
- Text and subtitles close nothing; a selected gap or range behaves as with Delete. The entry is greyed while the part generates, like Delete, and the shortcut list has the new row.
---
 web/editor_actions.js   | 25 ++++++++++++++++++++++++-
 web/editor_menu.js      |  1 +
 web/editor_model.js     | 11 ++++++++---
 web/editor_select.js    | 12 +++++++++++-
 web/editor_transport.js |  1 +
 5 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/web/editor_actions.js b/web/editor_actions.js
index 4c03c0e3..4e8bbb2d 100644
--- a/web/editor_actions.js
+++ b/web/editor_actions.js
@@ -3,6 +3,7 @@
 // splitAt        (record, ids, frame, {by})    <-> Split (B)
 // trimAt         (record, ids, frame, edge, {by}) <-> Trim before/after (Q/W)
 // removeParts    (record, ids)                 <-> Delete / Backspace / Cut
+// rippleRemoveParts (record, ids)              <-> Ripple delete (Shift+Delete / Shift+Backspace)
 // removeGaps     (record, gap|null)            <-> Remove gaps / Delete a gap
 // duplicateParts (record, ids)                 <-> Duplicate (D)
 // copyTo         (record, ids, at)             <-> Copy + Paste at the playhead
@@ -12,7 +13,7 @@
 // an explicit track must be an original lane of the group. No snapping here.
 // A cut by the user (the default) takes the block from the agent; by: 'agent' keeps its mark.
 import * as model from './editor_model.js';
-import {assertUnlocked} from './editor_text_model.js';
+import {assertUnlocked, isText} from './editor_text_model.js';
 import {copyContent, pasteContent, playheadTargets, removableGaps} from './editor_room.js';
 
 const end = clip => clip.start + clip.frames;
@@ -49,6 +50,28 @@ export function trimAt(record, ids, frame, edge, {by = 'user'} = {}) {
 export function removeParts(record, ids) {
     return edit(() => model.remove(record, linkedIds(record, ids)));
 }
+// Delete the parts, then close only the time they took (a gap that was already there stays), right to left
+// so earlier spans keep their frames. A span that cannot close stays open and is listed in `skipped`.
+// Text and subtitles only lie over the picture, so deleting them closes nothing.
+export function rippleRemoveParts(record, ids) {
+    ids = linkedIds(record, ids);
+    const taken = record.tracks.flatMap(track => track.clips).filter(clip => ids.includes(clip.id) && !isText(clip))
+        .sort((a, b) => a.start - b.start), spans = [];
+    for (const clip of taken) {
+        const last = spans.at(-1);
+        if (last && clip.start <= last.end) last.end = Math.max(last.end, end(clip));
+        else spans.push({start: clip.start, end: end(clip)});
+    }
+    let next = removeParts(record, ids); const skipped = [];
+    for (const span of spans.reverse()) {
+        try { next = edit(() => model.closeSpan(next, span.end, span.end - span.start)); }
+        catch (error) {
+            if (!(error instanceof model.EditError) || !['busy', 'locked', 'overlap'].includes(error.code)) throw error;
+            skipped.push({start: span.start, track: error.track, code: error.code});
+        }
+    }
+    return {record: next, closed: spans.length - skipped.length, skipped: skipped.reverse()};
+}
 export function removeGaps(record, gap) {
     if (gap !== null) {
         check(gap && record.tracks.some(track => track.id === gap.track));
diff --git a/web/editor_menu.js b/web/editor_menu.js
index 6fadae25..7bc6b847 100644
--- a/web/editor_menu.js
+++ b/web/editor_menu.js
@@ -41,6 +41,7 @@ export function menuItems(context) {
         command('x', t('Cut', '剪切'), `${modifier}+X`, copyable && !generating),
         command('d', t('Duplicate', '创建副本'), `${modifier}+D`, copyable),
         command('delete', t('Delete', '删除'), 'Delete', !generating),
+        command('ripple', t('Ripple delete', '波纹删除'), 'Shift+Delete', !generating),
         command('b', t('Split', '剪开'), `${modifier}+B`, !splitBusy && canSplit, 'split'),
     ] : [
         command('v', t('Paste', '粘贴'), `${modifier}+V`, commands.canPaste()),
diff --git a/web/editor_model.js b/web/editor_model.js
index d4a70d8e..0678e2fb 100644
--- a/web/editor_model.js
+++ b/web/editor_model.js
@@ -654,15 +654,20 @@ export function closeGap(record, trackId, frame) {
     check(whole(frame), 'range');
     const gap = gaps(record, trackId).find(item => frame >= item.start && frame < item.start + item.frames);
     if (!gap) return parse(record);
-    const from = gap.start + gap.frames;
+    return closeSpan(record, gap.start + gap.frames, gap.frames);
+}
+// Move everything that starts at `from` or later `frames` earlier on every track, the way a closed gap does.
+// Content that would land on a part that stays, a locked track or a generating part refuses the whole move.
+export function closeSpan(record, from, frames) {
+    check(whole(from) && whole(frames, 1) && frames <= from, 'range');
     for (const track of record.tracks) {
         const moving = track.clips.filter(clip => clip.start >= from), fixed = track.clips.filter(clip => clip.start < from);
         const code = moving.some(clip => ['queued', 'running'].includes(clip.pending)) ? 'busy'
             : moving.length && track.locked ? 'locked'
-                : moving.some(clip => fixed.some(other => overlaps(other, clip.start - gap.frames, clip.frames))) ? 'overlap' : null;
+                : moving.some(clip => fixed.some(other => overlaps(other, clip.start - frames, clip.frames))) ? 'overlap' : null;
         if (code) { const error = new EditError(code); error.track = track.id; throw error; }
     }
-    const next = copy(record); shift(next, from, -gap.frames); return finish(next);
+    const next = copy(record); shift(next, from, -frames); return finish(next);
 }
 export function setVolume(record, id, volume) {
     const next = copy(record), track = trackOf(next, id); check(track, 'missing'); check(track.kind === 'audio', 'track');
diff --git a/web/editor_select.js b/web/editor_select.js
index 764d0a25..5665ddf5 100644
--- a/web/editor_select.js
+++ b/web/editor_select.js
@@ -82,6 +82,8 @@ export function createSelectionActions({state, t = en => en, actions = {}, clipb
     }
     function run(key) {
         try {
+            // Ripple delete only differs for parts; a selected gap or range is deleted as with Delete.
+            if (key === 'ripple' && state.selection?.kind !== 'clip') key = 'delete';
             const ids = selectedIds(state.record, state.selection);
             if (key === 'a') { state.select(selection(unlockedIds(state.record))); return {ok: true}; }
             if (['b', 'q', 'w'].includes(key) && !playheadIds(state.record, state.selection, state.playhead).length) {
@@ -99,6 +101,14 @@ export function createSelectionActions({state, t = en => en, actions = {}, clipb
                     result.removed && state.selection?.kind === 'gap' ? {selectionAfter: null} : {});
                 return {ok: !!result.removed, ...(result.removed ? {} : {reason: result.skipped[0]?.code || 'no_gap'}), removed: result.removed, skipped: result.skipped};
             }
+            if (key === 'ripple') {
+                const status = deletionStatus(state.record, state.selection);
+                if (!status.ok) return status.reason === 'busy' ? report(new model.EditError(status.reason)) : status;
+                const result = actionsModel.rippleRemoveParts(state.record, ids);
+                state.apply(t('Ripple delete', '波纹删除'), () => result.record, {selectionAfter: null});
+                if (result.skipped.length) actions.notify?.(t('Deleted. The content after it cannot move earlier, so the gap remains.', '已删除。后面的内容无法前移，空隙已保留。'));
+                return {ok: true, closed: result.closed, skipped: result.skipped};
+            }
             if (key === 'delete' || key === 'backspace') {
                 const status = deletionStatus(state.record, state.selection);
                 if (!status.ok) return status.reason === 'busy' ? report(new model.EditError(status.reason)) : status;
@@ -137,7 +147,7 @@ export function createSelectionActions({state, t = en => en, actions = {}, clipb
         const deleting = ['delete', 'backspace'].includes(key) && ['clip', 'gap', 'range'].includes(state.selection?.kind);
         const trimming = !event.ctrlKey && !event.metaKey && !event.shiftKey && ['q', 'w'].includes(key);
         if (!command && !deleting && !trimming) return false;
-        event.preventDefault(); event.stopPropagation(); run(key); return true;
+        event.preventDefault(); event.stopPropagation(); run(deleting && event.shiftKey ? 'ripple' : key); return true;
     }};
 }
 
diff --git a/web/editor_transport.js b/web/editor_transport.js
index 85b1c787..537d308f 100644
--- a/web/editor_transport.js
+++ b/web/editor_transport.js
@@ -39,6 +39,7 @@ registerShortcuts([
     row('redo', 'Ctrl / Cmd + Shift + Z', 'Redo', '重做', 'edit'),
     row('split', 'Ctrl / Cmd + B', 'Split', '剪开', 'edit'),
     row('delete', 'Delete / Backspace', 'Delete', '删除', 'edit'),
+    row('ripple', 'Shift + Delete / Backspace', 'Delete the selected clip and close the gap', '删除选中的片段并合上空隙', 'edit'),
     row('fit', 'Shift + Z', 'Fit all', '看全部', 'timeline', event => !event.ctrlKey && !event.metaKey && !event.altKey && event.shiftKey && event.key.toLowerCase() === 'z'),
 ]);
 export function registerEditorShortcuts(audioRows = [], speedRows = []) {

From 94141bdbbf1d888b665c870f7a6ad694d9690b6c Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 13:02:15 +0000
Subject: [PATCH 14/26] Keep int8 attention outputs on a Windows card for
 requests below the first measured size

The output decision for small requests on a Windows card now reads the measured
curve below the first Windows measurement, still with the Windows margin, instead
of the held figure that moved those outputs to host memory for a small shortfall.
---
 freevideo_engine/policy.py | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/freevideo_engine/policy.py b/freevideo_engine/policy.py
index b1cb74e6..673b462d 100644
--- a/freevideo_engine/policy.py
+++ b/freevideo_engine/policy.py
@@ -495,15 +495,27 @@ def windows_int8_refinement_heads(engine, canvas, allocator_limit, *, windows=Fa
     return {'head_chunk': 2} if need is not None and need > allocator_limit else None
 
 
-def int8_gpu_output_need(tokens, windows=False, full_tail=False):
+# Windows has no measurement below 72576 tokens, so int8_gpu_output_need holds
+# the 72576 figure there. Whether the outputs stay on the card is decided with
+# the PRO 6000 curve carried over instead: it measures 0.78 GiB less at 55944
+# tokens than at 72576, and the Windows figures run 0.03 GiB above it at 72576.
+# The 16-step reference schedule charges 0.22 GiB of modulation tables to the
+# budget, which moved a 56721-token request on a 4.75 GiB budget to host
+# outputs for a 0.18 GiB shortfall against the clamped figure.
+INT8_GPU_OUTPUT_PEAKS_WINDOWS_LOW = ((55944, 3.43),) + INT8_GPU_OUTPUT_PEAKS_WINDOWS
+
+
+def int8_gpu_output_need(tokens, windows=False, full_tail=False, below_measured=False):
     """Bytes the int8 staging path needs with its attention outputs on the GPU.
 
     Windows has no full-tail measurement, so it returns None there: the caller
-    keeps the FP8-derived estimate 0.3.3 used."""
+    keeps the FP8-derived estimate 0.3.3 used. ``below_measured`` carries the
+    PRO 6000 curve under the first Windows measurement instead of holding it."""
     if full_tail and windows:
         return None
     peaks = (INT8_GPU_OUTPUT_PEAKS_FULL_TAIL if full_tail
-             else INT8_GPU_OUTPUT_PEAKS_WINDOWS if windows else INT8_GPU_OUTPUT_PEAKS)
+             else (INT8_GPU_OUTPUT_PEAKS_WINDOWS_LOW if below_measured else INT8_GPU_OUTPUT_PEAKS_WINDOWS) if windows
+             else INT8_GPU_OUTPUT_PEAKS)
     margin = INT8_GPU_OUTPUT_MARGIN_WINDOWS if windows else INT8_GPU_OUTPUT_MARGIN
     tokens = 72576 if tokens is None else tokens
     if tokens <= peaks[0][0]:
@@ -1386,7 +1398,7 @@ def held(group):
             # was an FP8 surcharge absorbed by that path's larger estimate.
             # Windows has its own measurement (INT8_GPU_OUTPUT_PEAKS_WINDOWS)
             # and keeps the FP8-derived estimate wherever that one is lower.
-            need = int8_gpu_output_need(effective_tokens, windows=desktop, full_tail=lora)
+            need = int8_gpu_output_need(effective_tokens, windows=desktop, full_tail=lora, below_measured=desktop)
             if desktop:
                 need = min(fp8_residual_need + GPU_ATTENTION_OUTPUT_BYTES, need or float('inf'))
             cpu_outputs = gpu_budget < need

From 978ff98b6ec33b98ee63c2b6a81e93e0336dd158 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 21:57:34 +0000
Subject: [PATCH 15/26] Progress estimate: reference rows past the measured
 share weigh less, so a long reference video...

Progress estimate: reference rows past the measured share weigh less, so a long reference video no longer shows a total far above the real time
---
 freevideo_engine/stage_estimate.py | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/freevideo_engine/stage_estimate.py b/freevideo_engine/stage_estimate.py
index 884e585d..d51956a0 100644
--- a/freevideo_engine/stage_estimate.py
+++ b/freevideo_engine/stage_estimate.py
@@ -25,6 +25,13 @@
 # (B200: linear in the row count, 1.4x at 960x544 and 1.85x at 1664x960);
 # canvases past the measured size keep the largest measured weight.
 REFERENCE_VIDEO_PAIR_WEIGHT = 4.
+# The B200 weights above were measured up to 8,696 reference rows on a 73,320-row
+# canvas (12% of its rows). Past that share a row adds less: an 8 s reference video
+# (50,928 rows) on a 5060 Ti, first pass 25,536 and second pass 57,456 generated
+# rows, ran at 110 s and 173 s a step, which a constant 1.6 to 1.7 rows per
+# reference row reproduces and the 2.4 and 4.2 above overshoot 1.6 and 2.6 times.
+REFERENCE_CALIBRATED_SHARE = .12
+REFERENCE_VIDEO_BEYOND_WEIGHT = 1.45
 DEFAULT_INTERVAL = [.45, 2.2]
 STAGES = ('encode', 'load', 'pass1', 'upscale', 'pass2', 'decode_save')
 PARAMS_PATH = Path(__file__).with_name('stage_estimate_params.json')
@@ -220,9 +227,13 @@ def stream_features(h, r, i):
 
 def _reference_rows(h, r, x):
     # Measured on NVIDIA only; the Apple fit keeps one row per reference token.
-    weight = 1. if _apple(h) else 1. + REFERENCE_VIDEO_PAIR_WEIGHT*min(x, 1.)
-    return (weight*float(_num(r, 'reference_video_tokens', 0.))
-            + float(_num(r, 'reference_audio_tokens', 0.)))
+    video, audio = float(_num(r, 'reference_video_tokens', 0.)), float(_num(r, 'reference_audio_tokens', 0.))
+    if _apple(h):
+        return video + audio
+    weight = 1. + REFERENCE_VIDEO_PAIR_WEIGHT*min(x, 1.)
+    # Rows inside the measured share keep the measured weight; the rest never weigh more.
+    measured = min(video, REFERENCE_CALIBRATED_SHARE*x*TOKEN_UNIT)
+    return weight*measured + min(weight, REFERENCE_VIDEO_BEYOND_WEIGHT)*(video-measured) + audio
 
 
 def step_parts(h, r, i, p):

From 0c1778569b6d3269395677a1d163976bbd84f79d Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 3 Nov 2026 23:41:10 +0000
Subject: [PATCH 16/26] Accept a single sound-led part whose length is not on
 the picture grid, so a sound range of any...

Accept a single sound-led part whose length is not on the picture grid, so a sound range of any length can be generated
---
 freevideo_engine/adaptive.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/freevideo_engine/adaptive.py b/freevideo_engine/adaptive.py
index 9963b8ef..beb0fadd 100644
--- a/freevideo_engine/adaptive.py
+++ b/freevideo_engine/adaptive.py
@@ -785,6 +785,11 @@ def complete_observation(metrics, canvas, output, artifacts, telemetry):
         output_frames = (count * canvas['fps'] + rate - 1) // rate
         if hidden or not 0 < output_frames <= expected:
             raise ValueError('Original audio exceeds the generated canvas')
+        if isinstance(original_audio.get('segment'), dict):
+            # A chain part keeps its whole picture grid; the join trims the tail.
+            output_frames = expected
+        if hidden or not 0 < output_frames <= expected:
+            raise ValueError('Original audio exceeds the generated canvas')
     if continuation is not None:
         from .continuation import OVERLAP_FRAMES
         if (not isinstance(continuation, dict) or continuation.get('overlap_frames') != OVERLAP_FRAMES

From 770a5c8d0744a29c3a9ca9f040d5921775e07165 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 00:59:43 +0000
Subject: [PATCH 17/26] Fold videos made by one task under the newest in Recent
 videos and Creations

---
 freevideo_engine/comfy_library.py | 76 ++++++++++++++++++++++++++++++-
 web/health.js                     |  2 +-
 web/library.css                   |  7 +++
 web/library.js                    | 27 ++++++++---
 web/studio.css                    |  6 +++
 web/studio_recent.js              | 23 ++++++++--
 web/task_groups.js                | 45 ++++++++++++++++++
 7 files changed, 174 insertions(+), 12 deletions(-)
 create mode 100644 web/task_groups.js

diff --git a/freevideo_engine/comfy_library.py b/freevideo_engine/comfy_library.py
index a5188828..c3eef4fa 100644
--- a/freevideo_engine/comfy_library.py
+++ b/freevideo_engine/comfy_library.py
@@ -1,5 +1,6 @@
 """Browse completed FreeVideo outputs across ComfyUI/browser restarts."""
 import asyncio
+import hashlib
 from contextlib import nullcontext
 import io
 import json
@@ -66,6 +67,77 @@ def _agent(folder):
     return {key: str(value[key])[:120] for key in ('job', 'label', 'project', 'client') if value.get(key)}
 
 
+def _identity_of(root, value):
+    """The library identity of a video path named by a run, or None for a file elsewhere."""
+    try:
+        relative = Path(value).resolve().relative_to(Path(root).resolve() / 'FreeVideo')
+    except (OSError, ValueError, TypeError):
+        return None
+    identity = '/'.join(relative.parts[:2])
+    return identity if len(relative.parts) == 3 and relative.name == 'video.mp4' and _ID.fullmatch(identity) else None
+
+
+def _source_identity(root, folder, report):
+    """The saved video this run started from: the preview it upscales, or the footage it continues."""
+    source = (report.get('upscaled_preview') or {}).get('output') if isinstance(report.get('upscaled_preview'), dict) else None
+    if not source:
+        try:
+            with (folder / 'comfy-request.json').open('rb') as stream:
+                data = stream.read(1024 * 1024 + 1)
+            command = json.loads(data).get('command') if len(data) <= 1024 * 1024 else None
+            if isinstance(command, list) and '--continue-from' in command:
+                source = command[command.index('--continue-from') + 1]
+        except (OSError, ValueError, AttributeError, IndexError):
+            pass
+    return _identity_of(root, source) if isinstance(source, str) else None
+
+
+def _prompt_digest(folder):
+    try:
+        with os.fdopen(os.open(folder / 'prompt.txt', os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0)
+                                | getattr(os, 'O_BINARY', 0)), 'rb') as stream:
+            data = stream.read(_PROMPT_BYTES + 1)
+        text = data.decode('utf-8').strip() if len(data) <= _PROMPT_BYTES else ''
+    except (OSError, ValueError):
+        return None
+    return hashlib.sha256(text.encode('utf-8')).hexdigest() if text else None
+
+
+def _tasks(root, rows, folders, reports):
+    """Name each row's task: the earliest video connected to it by a preview and its upscale, a continuation,
+    one agent job, or the same prompt text on the same day. A video with no such link is its own task."""
+    parent = {row['id']: row['id'] for row in rows}
+    def find(item):
+        while parent[item] != item:
+            parent[item] = parent[parent[item]]
+            item = parent[item]
+        return item
+    seen = {}
+    for row in rows:
+        identity = row['id']
+        tokens = ['id:' + identity]
+        source = _source_identity(root, folders[identity], reports[identity])
+        if source:
+            tokens.append('id:' + source)
+        if row.get('agent', {}).get('job'):
+            tokens.append('job:' + row['agent']['job'])
+        digest = _prompt_digest(folders[identity])
+        if digest:
+            tokens.append('prompt:%s:%s' % (identity.split('/', 1)[0], digest))
+        for token in tokens:
+            if token in seen:
+                parent[find(identity)] = find(seen[token])
+            else:
+                seen[token] = identity
+    groups = {}
+    for row in rows:
+        groups.setdefault(find(row['id']), []).append(row)
+    for members in groups.values():
+        earliest = min(members, key=lambda row: (row['created_at'], row['id']))['id']
+        for row in members:
+            row['task'] = earliest
+
+
 def _favorite(path):
     """A missing or damaged optional sidecar does not hide a saved video."""
     saved = path.with_suffix('.favorite.json')
@@ -133,7 +205,7 @@ def list_videos(output_directory, *, before=None, limit=24, favorite=None):
                 candidates.append((key, path, info))
         except (OSError, ValueError):
             continue
-    rows, unreadable = [], []
+    rows, unreadable, folders, reports = [], [], {}, {}
     for key, path, info in sorted(candidates, key=lambda item: item[0], reverse=True):
         relative = Path('FreeVideo') / key[1] / 'video.mp4'
         if relative.as_posix() in hidden:
@@ -171,6 +243,7 @@ def list_videos(output_directory, *, before=None, limit=24, favorite=None):
                 agent = None
             if agent:
                 summary['agent'] = agent
+            folders[key[1]], reports[key[1]] = path.parent, report
             rows.append(dict(summary, id=key[1], bytes=info.st_size, favorite=is_favorite,
                              created_at=datetime.fromtimestamp(info.st_mtime, timezone.utc).isoformat(),
                              cursor=str(key[0]) + ':' + key[1]))
@@ -182,6 +255,7 @@ def list_videos(output_directory, *, before=None, limit=24, favorite=None):
             break
     more = len(rows) > limit
     rows = rows[:limit]
+    _tasks(root, rows, folders, reports)
     next_cursor = rows[-1]['cursor'] if more else None
     for row in rows:
         row.pop('cursor')
diff --git a/web/health.js b/web/health.js
index a7586387..e2bbb306 100644
--- a/web/health.js
+++ b/web/health.js
@@ -16,7 +16,7 @@ const launchVisit = query.get('freevideo') === 'launch';
 export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_confirm_settings.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'chain_rules.js', 'timed_prompt.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_stems.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'image_lora.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
-    'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
+    'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js', 'task_groups.js',
     'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'pass_mode.js','setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'other_usage.js', 'studio_queue.js', 'studio_size.js',
     'toolbar_position.js', 'updates.js', 'view_navigation.js', 'wordmark.js', 'workspace_restore.js', 'cast_library.js', 'media_upload.js', 'whitebox_encode.js', 'whitebox_mp4.js', 'whitebox_recording.js', 'whitebox_render.js', 'whitebox_scenes.js', 'whitebox_worker.js',
     'empty_prompt_notice.js', 'feature_tour.js', 'feature_tour_content.js', 'howto.js', 'swap_lora.js', 'tour_try.js', 'tutorial_book.js', 'tutorial_book_content.js'];
diff --git a/web/library.css b/web/library.css
index 05cc0304..fba625bb 100644
--- a/web/library.css
+++ b/web/library.css
@@ -90,3 +90,10 @@
 .fv-library .fv-library-unreadable{margin:8px;text-align:center}.fv-library .fv-library-unreadable:empty{display:none}
 @media(max-width:680px){.fv-library-tools{gap:0}.fv-library .fv-library-header{grid-template-columns:auto minmax(0,1fr) auto}.fv-library-header h2{text-align:center}.fv-library-header button{white-space:nowrap}.fv-studio.fv-library .fv-library-header button{padding-left:6px;padding-right:6px}}
 .fv-library-message .fv-issue-button{margin:4px 0 4px 8px;vertical-align:middle}
+/* Videos of one task fold under the newest: its picture shows one more edge behind it. Opened, the cover and each video of the task sit on their own raised ground, with a gap between them. */
+.fv-library-card[hidden]{display:none}
+.fv-library-card.fv-task-head:not(.fv-task-open) .fv-library-picture{box-shadow:4px -4px 0 0 var(--fv-sheen)}
+.fv-library .fv-library-card.fv-task-open,.fv-library .fv-library-card.fv-task-member{background:var(--fv-raised);border-radius:var(--fv-r-md)}
+.fv-library .fv-library-card.fv-task-member{animation:fv-task-reveal .2s ease}
+@keyframes fv-task-reveal{from{opacity:0;transform:translateY(-4px)}}
+@media(prefers-reduced-motion:reduce){.fv-library .fv-library-card.fv-task-member{animation:none}}
diff --git a/web/library.js b/web/library.js
index eab223fe..162a41aa 100644
--- a/web/library.js
+++ b/web/library.js
@@ -5,6 +5,7 @@ import { videoUnavailableText } from './studio_extend.js';
 import { topDialog } from './dialog_keys.js';
 import { isNetworkTypeError, connectionLostText } from './browser_extension.js';
 import { issueButton } from './issue_button.js';
+import { applyTasks, toggledTask } from './task_groups.js';
 
 const style = document.createElement('link');
 style.rel = 'stylesheet'; style.href = new URL('./library.css', import.meta.url).href; document.head.append(style);
@@ -321,6 +322,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
                 remove: () => remove(row)}));
             notice.textContent = '';
             for (const [file, card] of cards) card.setAttribute('aria-pressed', String(selecting ? picked.has(file) : file === selected));
+            fold();
         }
         // These are the saved generation's measurements, including when the
         // same MP4 has since been reused. Never substitute the active request.
@@ -414,7 +416,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
         // Other views of the library (the studio's Recent videos) drop it too.
         window.dispatchEvent(new CustomEvent('freevideo-library-deleted', {detail: {video: row.video}}));
         if (disposed) return;
-        rows.delete(row.video); cards.get(row.video)?.remove(); cards.delete(row.video);
+        rows.delete(row.video); cards.get(row.video)?.remove(); cards.delete(row.video); fold();
         if (selected === row.video) {
             selected = null; frame.replaceChildren(); links.replaceChildren(); date.textContent = geometry.textContent = '';
             stats.hidden = true; stats.replaceChildren(); budget.textContent = '';
@@ -427,6 +429,13 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
     // --- Selecting several creations ---
     const gb = bytes => `${(bytes / 2 ** 30).toFixed(bytes < 2 ** 30 ? 2 : 1)} GB`;
     const ordered = () => [...grid.querySelectorAll('.fv-library-card')];
+    // The videos of one task fold under the newest; one task is unfolded at a time, and picking shows every card.
+    let unfolded = null;
+    function fold() {
+        const order = ordered().map(card => card.dataset.video);
+        if (!order.some(video => rows.get(video)?.task === unfolded)) unfolded = null;
+        applyTasks({cards, rows, order, open: unfolded, selecting, selected, t, label: video => cardLabel(rows.get(video))});
+    }
     const dayOf = video => (rows.get(video)?.id || '').slice(0, 10);
     const lastDay = () => dayOf(ordered().at(-1)?.dataset.video);
     const dayName = day => {
@@ -499,6 +508,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
             card.classList.toggle('fv-picked', selecting && picked.has(video));
             card.setAttribute('aria-pressed', String(selecting ? picked.has(video) : video === selected));
         }
+        fold();
         pickAll.disabled = deleting; pickNone.disabled = deleting || !picked.size;
         for (const heading of grid.querySelectorAll('.fv-library-day')) {
             const videos = ordered().map(card => card.dataset.video).filter(video => dayOf(video) === heading.dataset.day);
@@ -623,7 +633,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
                 removed.add(video);
                 window.dispatchEvent(new CustomEvent('freevideo-library-deleted', {detail: {video}}));
                 if (disposed) continue;
-                rows.delete(video); cards.get(video)?.remove(); cards.delete(video);
+                rows.delete(video); cards.get(video)?.remove(); cards.delete(video); fold();
             }
         };
         let undoFor = 10;
@@ -715,7 +725,12 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
         if (!row?.video || (favoritesOnly && !row.favorite)) return;
         rows.set(row.video, row);
         if (cards.has(row.video)) { syncFavorite(row); return; }
-        const card = button('', event => selecting ? pick(row.video, event.shiftKey) : select(rows.get(row.video)), 'fv-library-card');
+        const card = button('', event => {
+            if (selecting) { pick(row.video, event.shiftKey); return; }
+            // A cover with others under it also opens them in place.
+            unfolded = toggledTask(rows, ordered().map(item => item.dataset.video), row.video, unfolded);
+            select(rows.get(row.video)); fold();
+        }, 'fv-library-card');
         card.dataset.video = row.video;
         card.setAttribute('aria-label', cardLabel(row));
         card.setAttribute('aria-pressed', String(selecting ? picked.has(row.video) : row.video === selected));
@@ -737,7 +752,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
         }
         card.append(picture, el('span', row.agent?.label || timestamp(row)), el('small', row.agent?.label ? timestamp(row) : dimensions(row)));
         cards.set(row.video, card); first ? grid.prepend(card) : grid.append(card); thumbnails.observe(image);
-        if (selecting) regroup();
+        if (selecting) regroup(); else if (first) fold();
     }
     async function load(appendPage) {
         if (disposed || (loading && appendPage)) return false;
@@ -761,7 +776,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
                 if (!narrow.matches && rows.size) select(rows.values().next().value, false);
                 else dialog.dataset.detail = 'false';
             } else select(rows.get(selected), false);
-            ok = true; regroup();
+            ok = true; regroup(); fold();
             if (selectedWork) { const row = [...rows.values()].find(row => row.id === selectedWork || row.video === selectedWork); if (row) { select(row); selectedWork = null; } else if (next) queueMicrotask(() => load(true)); }
         } catch (error) {
             if (!disposed && round === loadRound && error.name !== 'AbortError') {
@@ -799,7 +814,7 @@ export function openLibrary(t, {upscale = null, selectedWork = null, extend = nu
     const deletedElsewhere = event => {
         const video = event.detail?.video;
         if (!video || !rows.has(video)) return;
-        rows.delete(video); cards.get(video)?.remove(); cards.delete(video);
+        rows.delete(video); cards.get(video)?.remove(); cards.delete(video); fold();
         if (selected === video) { selected = null; frame.replaceChildren(); links.replaceChildren(); date.textContent = geometry.textContent = ''; stats.hidden = true; stats.replaceChildren(); budget.textContent = ''; dialog.dataset.detail = 'false'; }
         picked.delete(video);
     };
diff --git a/web/studio.css b/web/studio.css
index 648fd686..fecdec1a 100644
--- a/web/studio.css
+++ b/web/studio.css
@@ -290,3 +290,9 @@
 .fv-studio .fv-swap-meter[data-indeterminate=true]>i{width:32%;animation:fv-swap-sweep 1.4s ease-in-out infinite}
 @keyframes fv-swap-sweep{from{transform:translateX(-100%)}to{transform:translateX(320%)}}
 @media (max-width:480px){.fv-studio .fv-swap-slots{grid-template-columns:1fr}.fv-studio .fv-swap-source{order:1}.fv-studio .fv-swap-sound{order:2}.fv-studio .fv-swap-person{order:3}}
+/* Recent videos: the same folding as Creations; the videos under an opened cover are indented. */
+.fv-studio .fv-recent-card[hidden]{display:none}
+.fv-recent-card.fv-task-head:not(.fv-task-open) .fv-library-picture{box-shadow:4px -4px 0 0 var(--fv-sheen)}
+.fv-studio .fv-recent-card.fv-task-member{margin-left:12px;animation:fv-task-reveal .2s ease}
+@keyframes fv-task-reveal{from{opacity:0;transform:translateY(-4px)}}
+@media(prefers-reduced-motion:reduce){.fv-studio .fv-recent-card.fv-task-member{animation:none}}
diff --git a/web/studio_recent.js b/web/studio_recent.js
index f1ded0f5..429619e5 100644
--- a/web/studio_recent.js
+++ b/web/studio_recent.js
@@ -1,5 +1,6 @@
 import { libraryPage, videoTimestamp, videoDimensions, videoThumbnailURL } from './library.js';
 import { icon } from './result_actions.js';
+import { applyTasks, toggledTask } from './task_groups.js';
 
 const KEY = 'fv-studio-recent-rail';
 const el = (tag, text, cls) => {
@@ -23,7 +24,8 @@ export function createRecentVideos(t, {body, onSelect}) {
     // as a panel over the preview; it starts closed each time, so a saved column never covers the picture.
     const wide = window.matchMedia('(min-width:1680px)');
     let expanded = true, open = false, selected = null, disposed = false, request = null, resizeTimer = null;
-    const cards = new Map();
+    const cards = new Map(), byVideo = new Map();
+    let order = [], unfolded = null;
     try { expanded = localStorage.getItem(KEY) !== 'false'; } catch {}
     function visibility() {
         const shown = wide.matches ? expanded : open;
@@ -85,9 +87,14 @@ export function createRecentVideos(t, {body, onSelect}) {
             target.src = target.dataset.src; thumbnails.unobserve(target);
         }
     }, {root: list, rootMargin: '80px'});
+    const cardLabel = video => `${videoTimestamp(byVideo.get(video), t)} · ${videoDimensions(byVideo.get(video))}`;
+    function fold() {
+        applyTasks({cards, rows: byVideo, order, open: unfolded, selected, t, label: cardLabel});
+    }
     function setSelected(video) {
         selected = video;
         for (const [file, card] of cards) card.setAttribute('aria-pressed', String(file === selected));
+        fold();
     }
     async function refresh() {
         if (disposed) return [];
@@ -96,22 +103,30 @@ export function createRecentVideos(t, {body, onSelect}) {
         try {
             const data = await libraryPage(t, {limit: 24, signal: controller.signal});
             if (disposed || controller.signal.aborted) return [];
-            thumbnails.disconnect(); cards.clear(); list.replaceChildren();
+            thumbnails.disconnect(); cards.clear(); byVideo.clear(); list.replaceChildren();
             // The library API returns newest first, with the same preview metadata.
             const rows = (data.items || []).filter(row => row?.video).slice(0, 24);
             for (const row of rows) {
                 const card = el('button', null, 'fv-recent-card'); card.type = 'button';
                 const date = videoTimestamp(row, t), dimensions = videoDimensions(row);
                 card.setAttribute('aria-label', `${date} · ${dimensions}`);
-                card.onclick = () => { onSelect(row); hidePanel({restoreFocus: true}); };
+                card.onclick = () => {
+                    // A cover with others under it opens them in place and keeps the panel; any other card is the choice.
+                    const next = toggledTask(byVideo, order, row.video, unfolded);
+                    onSelect(row);
+                    if (next !== unfolded || card.classList.contains('fv-task-head')) { unfolded = next; fold(); return; }
+                    hidePanel({restoreFocus: true});
+                };
                 const picture = el('div', null, 'fv-library-picture');
                 const image = el('img'); image.alt = ''; image.decoding = 'async';
                 image.dataset.src = videoThumbnailURL(row);
                 image.onerror = () => { image.hidden = true; };
                 picture.append(image);
                 card.append(picture, el('span', date), el('small', dimensions));
-                cards.set(row.video, card); list.append(card); thumbnails.observe(image);
+                cards.set(row.video, card); byVideo.set(row.video, row); list.append(card); thumbnails.observe(image);
             }
+            order = rows.map(row => row.video);
+            if (!order.some(video => byVideo.get(video).task === unfolded)) unfolded = null;
             message.textContent = t('Videos you generate appear here.', '生成的视频会显示在这里。');
             message.hidden = rows.length > 0; list.append(message);
             setSelected(selected);
diff --git a/web/task_groups.js b/web/task_groups.js
new file mode 100644
index 00000000..c8e7ead7
--- /dev/null
+++ b/web/task_groups.js
@@ -0,0 +1,45 @@
+// Videos made by one task (a preview and its upscale, a continuation, one agent job, the same prompt on one day)
+// share the `task` the library API gives them. A list shows the newest as the cover; the others fold under it
+// until the cover is pressed again. Both lists (Recent videos and Creations) fold with this one rule.
+
+// Marks the cards of `order` (video ids, newest first) for their tasks. `open` is the task now unfolded;
+// while picking several creations every card shows.
+export function applyTasks({cards, rows, order, open = null, selecting = false, selected = null, t, label}) {
+    const groups = new Map();
+    for (const video of order) {
+        const task = rows.get(video)?.task;
+        if (task) groups.set(task, [...(groups.get(task) || []), video]);
+    }
+    const heads = new Map();
+    for (const [task, videos] of groups) if (videos.length > 1) heads.set(videos[0], {task, videos});
+    for (const video of order) {
+        const card = cards.get(video);
+        if (!card) continue;
+        const task = rows.get(video)?.task, group = task && groups.get(task);
+        const folded = group && group.length > 1;
+        const shown = folded && (selecting || open === task);
+        const head = heads.get(video);
+        card.classList.toggle('fv-task-head', !!head);
+        card.classList.toggle('fv-task-open', !!head && shown);
+        card.classList.toggle('fv-task-member', !!folded && !head);
+        card.hidden = !!folded && !head && !shown;
+        if (head && !selecting) {
+            card.setAttribute('aria-expanded', String(shown));
+            card.setAttribute('aria-label', t(`${group.length} results`, `${group.length} 个结果`));
+            // A folded cover stands for every video under it.
+            if (!shown) card.setAttribute('aria-pressed', String(group.includes(selected)));
+        } else {
+            card.removeAttribute('aria-expanded');
+            card.setAttribute('aria-label', label(video));
+        }
+    }
+    return heads;
+}
+
+// The task to unfold when `video` is pressed: only a cover with others under it unfolds, and pressing it again folds it.
+export function toggledTask(rows, order, video, open) {
+    const task = rows.get(video)?.task;
+    if (!task || order.find(item => rows.get(item)?.task === task) !== video) return open;
+    if (order.filter(item => rows.get(item)?.task === task).length < 2) return open;
+    return open === task ? null : task;
+}

From bf436adb0ebe9e1ea4ee6b366841d5b7bb7e4258 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:01:28 +0000
Subject: [PATCH 18/26] Open the launcher when the bridge folder is redirected,
 and keep every failed model upgrade...

Open the launcher when the bridge folder is redirected, and keep every failed model upgrade error in the report with a pointer to Try again
---
 freevideo_engine/launcher/Main.qml   | 2 +-
 freevideo_engine/launcher_session.py | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/freevideo_engine/launcher/Main.qml b/freevideo_engine/launcher/Main.qml
index f1a5bdf4..2f7c8366 100644
--- a/freevideo_engine/launcher/Main.qml
+++ b/freevideo_engine/launcher/Main.qml
@@ -206,7 +206,7 @@ ApplicationWindow {
             return (u.blockers && u.blockers.length ? upgradeBlocker(u.blockers[0]) + t(" ", "") : u.error ? u.error.split("\n")[0] + "\n" : "")
                 + (u.step === "release" ? t("The faster model is in use; the old model files are kept for now.", "已在用更快的模型，旧模型文件暂时保留。")
                    : u.step === "switch" && !u.kept ? t("The previous model's files are all kept. Select \"Retry\" on the setup page to restore it.", "原来的模型文件都还在，在安装页点“重试”可恢复。")
-                   : t("Your previous model is unchanged and still works.", "原来的模型没有变化，可以继续使用。"))
+                   : t("Your previous model is unchanged and still works. Select \"Try again\", or report a problem.", "原来的模型没有变化，可以继续使用。可以点“重试”，或提交问题。"))
         return ""
     }
     function updateHeadline() {
diff --git a/freevideo_engine/launcher_session.py b/freevideo_engine/launcher_session.py
index 38c0f2b7..db5e23a3 100644
--- a/freevideo_engine/launcher_session.py
+++ b/freevideo_engine/launcher_session.py
@@ -224,8 +224,10 @@ def __init__(self, source=None, *, controller=None, store=None, updater=None, sm
             try:
                 self.bridge = create(launcher_root())
                 self.controller.update_bridge = self.bridge
-            except OSError:
+            except (OSError, ValueError) as error:
+                # Only updates started from the web page are lost; the launcher still opens.
                 self.bridge = None
+                print('Launcher bridge unavailable: %s' % (error if isinstance(error, ValueError) else type(error).__name__), file=sys.stderr)
         if self.form['environment_method'] == 'manual' and self.form['offline_runtime'] and not controller:
             root = io_path(self.form['offline_runtime'])
             if (root / 'portable.json').is_file():
@@ -1182,7 +1184,7 @@ def diagnostic_error(self):
         raw = self._raw_error()
         for state in (self.cleaner.state, self.importer.state, self.upgrade.state):
             value = state.get('error') or ''
-            if alias_failure(value) and value not in raw:
+            if (alias_failure(value) or (state is self.upgrade.state and state.get('status') == 'failed')) and value not in raw:
                 raw += ('\n' if raw else '') + value
         pack_report = self.image_pack_report()
         if pack_report:

From ae4735e1ee224a95cfae6286f946f0f74534547e Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:10:07 +0000
Subject: [PATCH 19/26] Point failed starts to ./freevideo diagnose, show a
 sign of life in logs while starting, and...

Point failed starts to ./freevideo diagnose, show a sign of life in logs while starting, and show the source switch while a download is handed over
---
 freevideo_engine/comfy_service.py    | 22 ++++++++++++++--------
 freevideo_engine/launcher_copy.py    |  2 +-
 freevideo_engine/launcher_session.py |  2 +-
 freevideo_engine/model_transfer.py   |  1 +
 freevideo_engine/terminal_ui.py      |  6 +++++-
 5 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/freevideo_engine/comfy_service.py b/freevideo_engine/comfy_service.py
index 11602648..5e9e48b1 100644
--- a/freevideo_engine/comfy_service.py
+++ b/freevideo_engine/comfy_service.py
@@ -29,6 +29,8 @@
 from .monitoring import save
 from . import engine_binding
 
+DIAGNOSE = 'If it keeps failing, run ./freevideo diagnose and send the report.'
+
 DEFAULT_PORT = 8188
 RECORD = 'comfyui-cli.json'
 STATE = 'service.json'
@@ -151,10 +153,10 @@ def install(root, source, machine, port, out=say):
         out('Installing ComfyUI for FreeVideo. This happens once; the next start takes seconds.')
         if host_setup(root, source, machine, comfy, download=not (comfy / 'main.py').is_file()):
             raise RuntimeError('ComfyUI could not be installed. Run the same command again to continue; '
-                               'downloaded files are kept.')
+                               'downloaded files are kept. ' + DIAGNOSE)
         python = managed_python(Path(root), comfy)
         if python is None:
-            raise RuntimeError('ComfyUI was installed, but its environment is incomplete. Run the same command again.')
+            raise RuntimeError('ComfyUI was installed, but its environment is incomplete. Run the same command again. ' + DIAGNOSE)
     else:
         add_node_packages(root, source, machine, comfy, out)
     if switching:
@@ -434,7 +436,7 @@ def wait_until_open(root, process, *, timeout=300, out=say):
     state_file = folder(root) / STATE
     deadline = time.monotonic() + timeout
     shown = time.monotonic()
-    interactive = sys.stdout.isatty()
+    interval = 15 if sys.stdout.isatty() else 30  # A log file gets a sign of life too, less often than a terminal.
     out('Starting ComfyUI ...')
     while time.monotonic() < deadline:
         state = read_json(state_file) or {}
@@ -445,12 +447,12 @@ def wait_until_open(root, process, *, timeout=300, out=say):
             raise RuntimeError(state.get('error') or 'ComfyUI could not start.')
         if process.poll() is not None:
             raise RuntimeError(state.get('error') if mine and state.get('error') else
-                               'The FreeVideo service stopped while starting. See %s.' % (folder(root) / 'service.log'))
-        if interactive and time.monotonic() - shown >= 15:
+                               'The FreeVideo service stopped while starting. See %s. %s' % (folder(root) / 'service.log', DIAGNOSE))
+        if time.monotonic() - shown >= interval:
             shown = time.monotonic()
             out('  still starting (%d s) ...' % (timeout - (deadline - time.monotonic())))
         time.sleep(.3)
-    raise RuntimeError('ComfyUI is still starting after %d s. See %s.' % (timeout, folder(root) / 'service.log'))
+    raise RuntimeError('ComfyUI is still starting after %d s. See %s. %s' % (timeout, folder(root) / 'service.log', DIAGNOSE))
 
 
 def respawn(root, state, *, port=None):
@@ -700,18 +702,22 @@ def open_command(root, *, port=None, browser=True, restart=False, out=say):
 
 def wait_for_running(root, timeout=300, absent=0., out=say):
     """Wait while the service starts; `absent` allows for one that a service manager starts shortly."""
-    started = time.monotonic()
+    started = shown = time.monotonic()
+    interval = 15 if sys.stdout.isatty() else 30
     while time.monotonic() - started < timeout:
         state = running(root)
         if state is not None and state.get('status') == 'open':
             return state
+        if state is not None and time.monotonic() - shown >= interval:
+            shown = time.monotonic()
+            out('  still starting (%d s) ...' % (shown - started))
         if state is None and time.monotonic() - started >= absent:
             previous = read_json(folder(root) / STATE) or {}
             if previous.get('status') == 'failed':
                 raise RuntimeError(previous.get('error') or 'ComfyUI could not start.')
             return None
         time.sleep(.3)
-    raise RuntimeError('ComfyUI is still starting. Check freevideo status.')
+    raise RuntimeError('ComfyUI is still starting. Check freevideo status. ' + DIAGNOSE)
 
 
 def status_command(root, out=say):
diff --git a/freevideo_engine/launcher_copy.py b/freevideo_engine/launcher_copy.py
index cc581f30..50a9ebbb 100644
--- a/freevideo_engine/launcher_copy.py
+++ b/freevideo_engine/launcher_copy.py
@@ -43,7 +43,7 @@
     ('Preparing installation', '准备安装'), ('Checking the environment', '正在检查运行环境'),
     ('Testing download sources', '正在测试下载源'), ('Preparing download tools', '正在准备下载工具'),
     ('GitHub mirror', 'GitHub 镜像'), ('attempt', '正在连接'),
-    ('fallback', '正在切换下载源'), ('route-retry', '正在切换连接'),
+    ('fallback', '正在切换下载源'), ('switching', '正在切换下载源'), ('route-retry', '正在切换连接'),
     ('verifying', '正在检查'), ('no-progress', '下载无进展'),
     ('slow-transfer', '持续低速'), ('resume-refused', '当前下载源不支持续传'),
     ('Download PyTorch + CUDA', '下载运行组件'),
diff --git a/freevideo_engine/launcher_session.py b/freevideo_engine/launcher_session.py
index db5e23a3..ffe39b8a 100644
--- a/freevideo_engine/launcher_session.py
+++ b/freevideo_engine/launcher_session.py
@@ -227,7 +227,7 @@ def __init__(self, source=None, *, controller=None, store=None, updater=None, sm
             except (OSError, ValueError) as error:
                 # Only updates started from the web page are lost; the launcher still opens.
                 self.bridge = None
-                print('Launcher bridge unavailable: %s' % (error if isinstance(error, ValueError) else type(error).__name__), file=sys.stderr)
+                print('Launcher bridge unavailable: %s' % type(error).__name__, file=sys.stderr)
         if self.form['environment_method'] == 'manual' and self.form['offline_runtime'] and not controller:
             root = io_path(self.form['offline_runtime'])
             if (root / 'portable.json').is_file():
diff --git a/freevideo_engine/model_transfer.py b/freevideo_engine/model_transfer.py
index a818676b..7feaee86 100644
--- a/freevideo_engine/model_transfer.py
+++ b/freevideo_engine/model_transfer.py
@@ -709,6 +709,7 @@ def resource_check():
                     # run_sdk/curl have joined their workers before this point.
                     # Reuse known byte ranges, including disjoint MS parts.
                     from .transfer_handoff import migrate
+                    network.event(networking,category=network.model_family(row),source=selected,file=path.name,action='switching')
                     # An explicit switch applies to this file even when the
                     # old provider has no portable resume map. Preserve those
                     # fragments on disk and report the restart separately.
diff --git a/freevideo_engine/terminal_ui.py b/freevideo_engine/terminal_ui.py
index 92045536..1b307522 100644
--- a/freevideo_engine/terminal_ui.py
+++ b/freevideo_engine/terminal_ui.py
@@ -200,7 +200,7 @@ def update(self, key, *, detail=None, done=None, total=None, resource=None, scop
                            estimated_step_seconds=row.get('estimated_step_seconds'),
                            step_elapsed_seconds=row.get('step_elapsed_seconds'))
                 row['event_tick'] = now
-            if not self.live and time.monotonic() - row['heartbeat'] >= 30:
+            if not self.live and time.monotonic() - row['heartbeat'] >= 10:
                 self.write('  … %s · %s · %s%s\n' % (row['label'], duration(time.monotonic() - row['started']),
                     row['detail'] + self.eta_text(row), ' · ' + self.resource if self.resource else ''))
                 row['heartbeat'] = time.monotonic()
@@ -539,6 +539,10 @@ def update(**values):
             elif kind == 'network' and event.get('action') == 'backend':
                 self.model_backend = {'hf-xet': 'HF Xet', 'modelscope-ranges': 'ModelScope parallel',
                                       'http-ranges': 'Parallel HTTP', 'hf-http': 'HF HTTP'}.get(event.get('method'), '')
+            elif kind == 'network' and event.get('action') == 'switching':
+                self.model_backend=''
+                update(done=0,total=0,rate=None,scope='switching',unit='bytes',
+                       detail='Switching current download to '+event.get('source','')+' · '+event.get('file',''))
             elif kind == 'network' and event.get('action') == 'manual-switch':
                 self.model_source=event.get('source','')
                 self.model_backend=''

From b150e548837f1b21ddf82ed40f1d7e6bf66f968e Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:13:02 +0000
Subject: [PATCH 20/26] Show the packed file count when the full log export is
 slow, and name the workflow-node...

Show the packed file count when the full log export is slow, and name the workflow-node connection step in setup progress
---
 freevideo_engine/comfy_launcher_runtime.py |  1 +
 freevideo_engine/diagnostics.py            |  4 +++-
 freevideo_engine/launcher/Main.qml         |  4 ++--
 freevideo_engine/launcher_copy.py          |  2 +-
 freevideo_engine/launcher_session.py       | 10 ++++++++--
 freevideo_engine/progress_timeline.py      |  1 +
 6 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/freevideo_engine/comfy_launcher_runtime.py b/freevideo_engine/comfy_launcher_runtime.py
index 367c3120..dd444694 100644
--- a/freevideo_engine/comfy_launcher_runtime.py
+++ b/freevideo_engine/comfy_launcher_runtime.py
@@ -1202,6 +1202,7 @@ def _install(self, accepted):
             if queue_busy(loopback_url(self.server_address or self.selection['url'])):
                 raise RuntimeError(ENGINE_UPDATE_WAITS + '. Try again after it finishes; the job is left running.')
             self._stop_server_for_setup(selected['url'])
+        self.stage('nodes', label='Connecting workflow nodes')
         engine_binding.rebind(selected['engine'], machine, selected['source'])
         self.stage('nodes', label='Install FreeVideo workflow')
         deployed = deploy(selected['root'], selected['source'], selected['engine'])
diff --git a/freevideo_engine/diagnostics.py b/freevideo_engine/diagnostics.py
index 48df0e79..bd34e4d4 100644
--- a/freevideo_engine/diagnostics.py
+++ b/freevideo_engine/diagnostics.py
@@ -237,7 +237,7 @@ def web_files(root, machine):
     return dict(error='No FreeVideo source is recorded')
 
 
-def collect(root, config, run, output, *, complete=False, extra_files=(), notes=''):
+def collect(root, config, run, output, *, complete=False, extra_files=(), notes='', progress=None):
     root, config = resolved(root.expanduser()), io_path(config.expanduser().absolute())
     run = io_path(run) if run is not None else None
     output = io_path(output)
@@ -270,6 +270,8 @@ def add(name, raw, truncated=False):
             manifest['files'].append({'file': name, 'bytes': len(data), 'truncated': truncated,
                                       'sha256': hashlib.sha256(data).hexdigest()})
             manifest['payload_bytes'] += len(data)
+            if progress is not None:
+                progress(len(manifest['files']))
 
         def add_path(name, path):
             if Path(path).name.lower() in SENSITIVE_FILES:
diff --git a/freevideo_engine/launcher/Main.qml b/freevideo_engine/launcher/Main.qml
index 2f7c8366..06beb9d5 100644
--- a/freevideo_engine/launcher/Main.qml
+++ b/freevideo_engine/launcher/Main.qml
@@ -485,7 +485,7 @@ ApplicationWindow {
                     objectName: "reportStatus"
                     visible: s.report.status !== "idle"; Layout.fillWidth: true; font.pixelSize: theme.micro
                     color: s.report.status === "error" ? theme.danger : theme.muted
-                    text: s.report.status === "running" ? t("Exporting full logs…", "正在导出完整日志…") :
+                    text: s.report.status === "running" ? t("Exporting full logs…", "正在导出完整日志…") + (s.report.files > 0 ? t(" · " + s.report.files + " files packed", " · 已打包 " + s.report.files + " 个文件") : "") :
                         s.report.status === "error" ? t("Export failed: ", "导出失败：") + s.report.error :
                         t("Report saved locally: ", "报告已保存到本机：") + s.report.path +
                         (s.report.collection_errors ? t("\nReport saved with some diagnostic information missing.", "\n报告已保存，部分诊断信息未能收集。") : "")
@@ -1481,7 +1481,7 @@ ApplicationWindow {
                             }
                             FText {
                                 visible: s.report.status !== "idle"; Layout.fillWidth: true; font.pixelSize: theme.micro; color: theme.muted
-                                text: s.report.status === "running" ? t("Exporting full logs…", "正在导出完整日志…") :
+                                text: s.report.status === "running" ? t("Exporting full logs…", "正在导出完整日志…") + (s.report.files > 0 ? t(" · " + s.report.files + " files packed", " · 已打包 " + s.report.files + " 个文件") : "") :
                                     s.report.status === "error" ? s.report.error : t("Saved: ", "已保存：") + s.report.path
                             }
                         }
diff --git a/freevideo_engine/launcher_copy.py b/freevideo_engine/launcher_copy.py
index 50a9ebbb..17960bf7 100644
--- a/freevideo_engine/launcher_copy.py
+++ b/freevideo_engine/launcher_copy.py
@@ -78,7 +78,7 @@
     ('Install ComfyUI packages', '安装 ComfyUI 组件'), ('Check ComfyUI dependencies', '检查 ComfyUI 环境'),
     ('Finish ComfyUI setup', '完成 ComfyUI 安装'), ('ComfyUI ready', 'ComfyUI 已就绪'),
     ('Prepare ComfyUI', '准备 ComfyUI'), ('Update ComfyUI packages', '更新 ComfyUI 组件'),
-    ('Install FreeVideo workflow', '安装 FreeVideo 工作流'),
+    ('Install FreeVideo workflow', '安装 FreeVideo 工作流'), ('Connecting workflow nodes', '正在连接工作流节点'),
     ('Open ComfyUI', '打开 ComfyUI'), ('Starting ComfyUI', '启动 ComfyUI'),
     ('Loading nodes and the web interface', '正在加载界面'),
     ('Still loading. This may take a few more minutes.', '仍在加载，可能还需要几分钟'),
diff --git a/freevideo_engine/launcher_session.py b/freevideo_engine/launcher_session.py
index ffe39b8a..7eca332b 100644
--- a/freevideo_engine/launcher_session.py
+++ b/freevideo_engine/launcher_session.py
@@ -1205,7 +1205,13 @@ def export_report(self, output, overwrite=False):
         notes = self.diagnostic_error()
         logs = tuple(path for _, path in self.controller.terminal_sources())
         replacements = [(self.token, '<REDACTED>')] if self.token else []
-        self.report = dict(status='running', path=str(output), error='')
+        started = time.monotonic()
+        self.report = dict(status='running', path=str(output), error='', files=0)
+
+        def packed(count):
+            # The count is shown only when packing takes longer than a few seconds.
+            if self.report.get('status') == 'running':
+                self.report = dict(self.report, files=count if time.monotonic() - started > 5 else 0)
 
         def work():
             target = Path(output)
@@ -1214,7 +1220,7 @@ def work():
             replacing = False
             try:
                 result = collect(root, root / 'machine.json', None, partial,
-                                 complete=True, extra_files=logs, notes=notes)
+                                 complete=True, extra_files=logs, notes=notes, progress=packed)
                 if partial != target:
                     replacing = True
                     os.replace(io_path(partial), io_path(target))
diff --git a/freevideo_engine/progress_timeline.py b/freevideo_engine/progress_timeline.py
index bec0de27..4e911e23 100644
--- a/freevideo_engine/progress_timeline.py
+++ b/freevideo_engine/progress_timeline.py
@@ -147,6 +147,7 @@
     'Hugging Face',
     'Importing offline packages',
     'Install FreeVideo workflow',
+    'Connecting workflow nodes',
     'Installing sampling cache',
     'Leaving more GPU memory for text encoding',
     'Load cached blocks and upload resident weights',

From 99503e65cc79fe2d1a7a834088cb6bbba96db9a7 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:13:45 +0000
Subject: [PATCH 21/26] Name the GPU detection and acceleration test steps in
 the launch progress

---
 freevideo_engine/launcher_copy.py | 2 +-
 freevideo_engine/portable.py      | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/freevideo_engine/launcher_copy.py b/freevideo_engine/launcher_copy.py
index 17960bf7..940e711f 100644
--- a/freevideo_engine/launcher_copy.py
+++ b/freevideo_engine/launcher_copy.py
@@ -85,7 +85,7 @@
     ('Checking configuration', '检查配置'), ('Check installation', '检查安装'),
     ('Verify bundled files', '校验离线包'), ('Check local files', '检查本地文件'),
     ('All bundled files verified', '离线包校验完成'),
-    ('Detecting your GPU and testing acceleration', '检测显卡与加速组件'),
+    ('Detecting the GPU', '正在检测显卡'), ('Testing acceleration', '正在测试加速组件'),
     ('Start ComfyUI', '启动 ComfyUI'), ('Open FreeVideo workflow', '打开 FreeVideo 工作流'),
     ('Ready', '已就绪'), ('Verified and ready', '已就绪'),
     ('Stopped; files retained', '已暂停，下载进度已保留'),
diff --git a/freevideo_engine/portable.py b/freevideo_engine/portable.py
index 86381c6b..f001830b 100644
--- a/freevideo_engine/portable.py
+++ b/freevideo_engine/portable.py
@@ -217,7 +217,7 @@ def initialize(root, progress=lambda **kw: None):
     from .locking import runtime_lock
     with runtime_lock(root/'engine/engine.lock', inherit=False) as descriptor, child_lease(descriptor):
         verify(root, value, progress)
-        progress(stage='gpu', detail='Detecting your GPU and testing acceleration', done=0, total=1)
+        progress(stage='gpu', detail='Detecting the GPU', done=0, total=1)
         from .hardware import detect
         hardware = detect()
         machine = configuration(root, value, hardware)
@@ -227,6 +227,7 @@ def initialize(root, progress=lambda **kw: None):
         # Reuse only this device/driver/runtime's local kernel receipt. No
         # foreign ready machine.json or precompiled GPU cache ships in a ZIP.
         from .kernel_capabilities import available_backends, readiness, receipt_path
+        progress(stage='gpu', detail='Testing acceleration', done=0, total=1)
         available_backends(hardware)
         if machine['prepared_format'] == 'int8_convrot':
             rows = json.loads(io_path(receipt_path()).read_text(encoding='utf-8')).get('kernel_probes', [])

From a31f23d50293e942bfec32cc28ea286693a03a58 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:29:40 +0000
Subject: [PATCH 22/26] Record audio in the Edit view: record against the
 picture and place the take on a sound track...

Record audio in the Edit view: record against the picture and place the take on a sound track, aligned with the picture
---
 freevideo_engine/comfy_editor.py  |   8 +-
 freevideo_engine/editor_export.py |   2 +-
 web/editor.css                    |   3 +-
 web/editor.js                     |  13 +-
 web/editor_audio.css              |   4 +-
 web/editor_audio.js               |  11 +-
 web/editor_library.js             |   6 +-
 web/editor_lifecycle.js           |   2 +-
 web/editor_menu.js                |   3 +-
 web/editor_model.js               |  37 ++++--
 web/editor_player.js              |  16 +--
 web/editor_record.css             |  43 +++++++
 web/editor_record.js              | 189 ++++++++++++++++++++++++++++++
 web/editor_record_model.js        |  84 +++++++++++++
 web/editor_text_model.js          |   4 +-
 web/editor_tracks.js              |  13 +-
 16 files changed, 399 insertions(+), 39 deletions(-)
 create mode 100644 web/editor_record.css
 create mode 100644 web/editor_record.js
 create mode 100644 web/editor_record_model.js

diff --git a/freevideo_engine/comfy_editor.py b/freevideo_engine/comfy_editor.py
index 35d8ba04..abde3549 100644
--- a/freevideo_engine/comfy_editor.py
+++ b/freevideo_engine/comfy_editor.py
@@ -187,9 +187,13 @@ def bounded(value, depth=0):
     if not _text(json.dumps(settings, ensure_ascii=False, allow_nan=False, separators=(',', ':')), 1024 * 1024):
         raise ValueError('Settings are too large')
     raw_tracks = record.get('tracks')
-    expected = [('v1', 'video'), ('a1', 'audio'), ('a2', 'audio'), ('a3', 'audio'), ('a4', 'audio'), ('a5', 'audio'), ('a6', 'audio')]
-    if not isinstance(raw_tracks, list) or len(raw_tracks) not in (2, 3, 7):
+    # v1 and a1, then an optional second sound track (a2), the recording sub-track under a1 (a3) and, only together with both, the three separated-sound tracks (a4-a6), in that order.
+    if not isinstance(raw_tracks, list) or len(raw_tracks) not in (2, 3, 4, 7):
         raise ValueError('Invalid tracks')
+    later = [raw.get('id') if isinstance(raw, dict) else None for raw in raw_tracks[2:]]
+    if later not in ([], ['a2'], ['a3'], ['a2', 'a3']):
+        raise ValueError('Invalid tracks')
+    expected = [('v1', 'video'), ('a1', 'audio')] + [(track_id, 'audio') for track_id in later]
     tracks, seen = [], {}
     for raw_track, (track_id, kind) in zip(raw_tracks, expected):
         if (not isinstance(raw_track, dict) or raw_track.get('id') != track_id or raw_track.get('kind') != kind
diff --git a/freevideo_engine/editor_export.py b/freevideo_engine/editor_export.py
index 9517c45c..b85ba971 100644
--- a/freevideo_engine/editor_export.py
+++ b/freevideo_engine/editor_export.py
@@ -113,7 +113,7 @@ def _layout(project):
         project = validate(project)
         raw_tracks = [t for t in project['tracks'] if not is_text_track(t)]
     if not isinstance(raw_tracks, list) or [t.get('id') for t in raw_tracks if isinstance(t, dict)] not in (
-            ['v1', 'a1'], ['v1', 'a1', 'a2'], ['v1', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6']):
+            ['v1', 'a1'], ['v1', 'a1', 'a2'], ['v1', 'a1', 'a3'], ['v1', 'a1', 'a2', 'a3'], ['v1', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6']):
         raise ExportError()
     tracks, seen = {}, set()
     for raw in raw_tracks:
diff --git a/web/editor.css b/web/editor.css
index 576689e8..9bb0997e 100644
--- a/web/editor.css
+++ b/web/editor.css
@@ -209,7 +209,8 @@
 .fv-editor .fv-ed-name-menu .fv-ed-delete-confirm{color:var(--fv-danger)}
 .fv-editor .fv-ed-name-menu .fv-ed-delete-confirm:not(:disabled):is(:hover,:focus-visible){background:var(--fv-danger-subtle)}
 .fv-ed-delete-question{margin:6px 10px 10px;line-height:1.5;overflow-wrap:anywhere;white-space:normal}
-.fv-ed-notice{position:absolute;bottom:340px;right:16px;max-width:min(560px,calc(100vw - 32px));border:1px solid var(--fv-border);background:var(--fv-card);padding:10px 14px;border-radius:8px;z-index:9;color:var(--fv-ink)}
+.fv-ed-notice{position:absolute;bottom:362px;right:300px;max-width:min(560px,calc(100vw - 32px));border:1px solid var(--fv-border);background:var(--fv-card);padding:10px 14px;border-radius:8px;z-index:9;color:var(--fv-ink)}
+@media(min-width:681px) and (max-width:1279px){.fv-ed-notice{right:32px;max-width:min(560px,calc(100vw - 330px))}}
 .fv-ed-notice .fv-issue-button{margin-left:12px;vertical-align:middle;pointer-events:auto}
 @media(max-width:680px){
  .fv-studio.fv-editor{grid-template-columns:minmax(0,1fr);grid-template-rows:auto minmax(max(0px,calc(180px - var(--fv-ed-description-growth,0px))),1fr) 40px var(--fv-ed-generation-row,auto) 40px 236px;overflow:hidden}
diff --git a/web/editor.js b/web/editor.js
index f4dcfb1d..b64a124d 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -26,6 +26,7 @@ import {createStemsIntegration} from './editor_stems.js';
 import {createSpeedComponent, readSpeedAudioSamples, handleSpeedKey, speedShortcuts} from './editor_speed.js';
 import {createEditorGenbar, loadEditorComponents, editorBlockStates, blockMessages} from './editor_genbar.js';
 import {createEditorMusic} from './editor_music.js';
+import {createEditorRecord, RECORD_ICON} from './editor_record.js';
 import {MAX_MUSIC_TEXT as MUSIC_TEXT_LIMIT} from './editor_music_model.js';
 import {createProgressConnection} from './progress_connection.js';
 import {createSelectionActions, deletionStatus, isMultiple, isTyping, playheadIds, removableGaps, removeGaps} from './editor_select.js';
@@ -457,7 +458,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
     // The nearest spot at or after the chosen one where a part of the same length fits.
     function emptySpot(selection) {
         if (!['range', 'gap'].includes(selection?.kind)) return null;
-        const range = selectionRange(selection), clips = state.record.tracks.filter(track => ['v1', 'a1', 'a2'].includes(track.id)).flatMap(track => track.clips);
+        const range = selectionRange(selection), clips = state.record.tracks.filter(track => ['v1', 'a1', 'a2', 'a3'].includes(track.id)).flatMap(track => track.clips);
         const starts = [range.start, ...clips.map(clip => clip.start + clip.frames).filter(at => at > range.start)].sort((a, b) => a - b);
         for (const start of starts) {
             if (clips.some(clip => clip.start < start + range.frames && clip.start + clip.frames > start)) continue;
@@ -470,7 +471,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
     function flushSpot(selection) {
         if (selection?.kind !== 'range') return null;
         const range = selectionRange(selection), most = model.RULES.minSeconds * model.FPS;
-        const clips = state.record.tracks.filter(track => ['v1', 'a1', 'a2'].includes(track.id)).flatMap(track => track.clips);
+        const clips = state.record.tracks.filter(track => ['v1', 'a1', 'a2', 'a3'].includes(track.id)).flatMap(track => track.clips);
         const end = Math.max(-1, ...state.record.tracks[0].clips.map(clip => clip.start + clip.frames).filter(at => at < range.start));
         if (end < 0 || range.start - end >= most || clips.some(clip => clip.start < range.start && clip.start + clip.frames > end)) return null;
         const moved = {kind: 'range', start: end, frames: range.frames, tracks: ['v1', 'a1']};
@@ -1401,7 +1402,8 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         finally { if (!disposed) updateSecondPass(); }
     }
     actions.runSecondPass = runSecondPass;
-    historyTools.append(toolUndo, toolRedo); editTools.append(split, remove, closeGap, previous);
+    const recordTool = toolButton(t('Record', '录音'), RECORD_ICON, () => {}, 'fv-ed-record-toggle'); recordTool.setAttribute('aria-pressed', 'false'); recordTool.dataset.tourId = 'record-entry';
+    historyTools.append(toolUndo, toolRedo); editTools.append(split, remove, closeGap, previous, recordTool);
     const pictureTools = createPictureTools({state, sources: store.sources, t, capabilities: () => capability, error});
     toolbar.append(historyTools, editTools, zoomHost); element.insertBefore(toolbar, tracksHost);
     const transportControls = createEditorTransport({element, preview, transport, toolbar, editTools, zoomHost, state, player, t, notify});
@@ -1413,6 +1415,8 @@ export function openEditor({api, app, from = null, panel = {}, components: given
     const audio = createAudioIntegration({state, player, t, error, adjust, library: libraryHost, store});
     stems = createStemsIntegration({state, api, queue, store, t, error, notify, toolbar, show: job => genbar?.update(job),
         restore: () => genbar?.update(mostRecentJob ? barJob(jobStatuses.get(mostRecentJob)) : null)});
+    const recording = createEditorRecord({state, player, t, error, notify, button: recordTool, bar: element, library: {importFiles: (files, options) => actions.importFiles(files, options)}});
+    element.insertBefore(recording.element, tracksHost);
     registerEditorShortcuts(AUDIO_SHORTCUTS, speedShortcuts);
     adjust.register('speed', createSpeedComponent({state, t, onError: error}));
     function selectedContent() {
@@ -1552,6 +1556,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
             if (tracks?.cancelGesture()) { event.preventDefault(); return; }
             if (document.fullscreenElement) { event.preventDefault(); document.exitFullscreen().catch(() => {}); return; }
         }
+        if (recording.keyboard(event)) return;
         if (inside && event.target.closest?.('.fv-ed-refs')) {
             // The reference pictures' own buttons and menu keep their keys: no timeline, audio or transport shortcut.
             for (let target = event.target; target && target !== element; target = target.parentNode) target.onkeydown?.(event);
@@ -1619,7 +1624,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 await store.activateProject(null).catch(() => {});
                 rememberView(); disposed = true; music.dispose(); guide?.dispose(); transportControls.dispose(); toolbarMore.dispose(); player.dispose();
                 textTools.dispose(); adjust.dispose(); notes.dispose(); pictureEdit.dispose();
-                audio.dispose(); stems?.dispose(); headerFit.dispose();
+                audio.dispose(); stems?.dispose(); recording.dispose(); headerFit.dispose();
                 listeners.splice(0).forEach(remove => remove());
                 for (const node of [element, ...element.querySelectorAll('*')]) for (const name of ['onclick', 'ondblclick', 'oninput', 'onchange', 'onkeydown', 'ondragstart']) node[name] = null;
                 unsubscribe(); stopSources(); library?.dispose(); genbar.dispose(); tracks?.dispose(); stopExport?.();
diff --git a/web/editor_audio.css b/web/editor_audio.css
index 498e0f5b..0a64fc85 100644
--- a/web/editor_audio.css
+++ b/web/editor_audio.css
@@ -3,8 +3,8 @@
 .fv-ed-audio-panel [hidden]{display:none!important}
 .fv-ed-track-view .fv-ed-track-head{justify-content:space-between;gap:4px;padding:0 6px}
 .fv-ed-track-head>svg{display:none}
-.fv-ed-track-head>span:not(.fv-ed-audio-track-controls){white-space:nowrap}
-.fv-ed-audio-track-controls{display:flex;gap:1px}
+.fv-ed-track-head>span:not(.fv-ed-audio-track-controls){white-space:nowrap;min-width:0;overflow:hidden;text-overflow:ellipsis}
+.fv-ed-audio-track-controls{display:flex;gap:1px;flex:none}
 .fv-ed-track-view .fv-ed-audio-track-switch{display:grid;place-items:center;padding:2px;width:24px;height:28px;border:0;border-radius:4px;background:transparent;opacity:.5;cursor:pointer}
 .fv-ed-audio-track-switch:hover,.fv-ed-audio-track-switch[aria-pressed=true]{opacity:1!important}
 .fv-ed-audio-track-switch[aria-pressed=true]{color:var(--fv-accent)!important}
diff --git a/web/editor_audio.js b/web/editor_audio.js
index 40c79aca..305b2f6e 100644
--- a/web/editor_audio.js
+++ b/web/editor_audio.js
@@ -238,7 +238,10 @@ export function attachAudioTracks(element, {state, t = en => en, actions = {}})
             for (const name of track.kind === 'audio' ? ['muted', 'solo', 'locked'] : ['muted', 'locked']) {
                 const active = !!track[name], button = el('button', 'fv-ed-audio-track-switch'); button.type = 'button'; button.dataset.flag = name; button.dataset.track = track.id;
                 const labels = {muted: active ? t('Unmute', '取消静音') : t('Mute this track', '静音这条轨道'), solo: active ? t('Hear all tracks', '恢复全部轨道') : t('Solo this track', '只听这条轨道'), locked: active ? t('Unlock', '解除锁定') : t('Lock this track', '锁定这条轨道')};
-                button.title = labels[name]; button.setAttribute('aria-label', button.title); button.setAttribute('aria-pressed', String(active));
+                button.title = labels[name];
+                // The recording track is mixed like the others but is only ever heard or muted: solo and lock stay in place, unavailable.
+                if (track.id === 'a3' && name !== 'muted') { button.disabled = true; button.title = name === 'solo' ? t('Not available on the recording track', '录音轨不能单独试听') : t('Not available on the recording track', '录音轨不能锁定'); }
+                button.setAttribute('aria-label', button.title); button.setAttribute('aria-pressed', String(active));
                 const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg'), path = document.createElementNS(svg.namespaceURI, 'path'); svg.setAttribute('viewBox', '0 0 16 16'); svg.setAttribute('aria-hidden', 'true'); path.setAttribute('d', paths[name]); svg.append(path); button.append(svg);
                 // Switches are view settings: they change every snapshot alike and never enter the undo history.
                 const activate = () => { try { state.settle(record => sound.setTrackFlag(record, track.id, name, !active)); } catch (error) { actions.editError?.(error); } };
@@ -337,6 +340,8 @@ export function createSpeechSpans(fetchSpans, {retry = 1000} = {}) {
     };
     return {map, want(keys) { keys.forEach(ask); }, get version() { return version; }, dispose() { disposed = true; }};
 }
+// A picture's own sound: still joined to it, or taken from it and kept.
+export const isOriginalSound = clip => !!clip.link || !!clip.detached_from;
 export function createAudioPreview({state, sources, api, volumePreview = new Map(), readSamples = null, error = () => {}, speech = null}) {
     let context = null, generation = 0, timer = null, identity = null, pending = false, disposed = false;
     const cache = new Map(), nodes = new Set(); let origin = 0, cursor = 0, previousPosition = 0;
@@ -422,10 +427,12 @@ export function createAudioPreview({state, sources, api, volumePreview = new Map
         finally { pending = false; }
     }
     return {
-        render({record, position, playing, playbackRate = 1}) {
+        render({record, position, playing, playbackRate = 1, silenceOriginal = false}) {
             speech?.want(sound.duckSources(record.tracks));
             if (!edited(record)) { if (identity) stop(); return false; }
             if (volumePreview.size) record = {...record, tracks: record.tracks.map(track => ({...track, clips: track.clips.map(clip => volumePreview.has(clip.id) ? {...clip, volume: volumePreview.get(clip.id)} : clip)}))};
+            // While a take is recorded the picture's own sound stays out of the mix.
+            if (silenceOriginal) record = {...record, tracks: record.tracks.map(track => ({...track, clips: track.clips.filter(clip => !isOriginalSound(clip))}))};
             if (!playing) { stop(); previousPosition = position; return true; }
             if (playbackRate !== 1) {
                 const unavailable = `shuttle:${playbackRate}`;
diff --git a/web/editor_library.js b/web/editor_library.js
index 25008146..ce6f383f 100644
--- a/web/editor_library.js
+++ b/web/editor_library.js
@@ -218,13 +218,13 @@ export function createEditorLibrary(host, {store, t, actions, state}) {
             if (row?.state !== 'ready') continue;
             const value = metadata(row, 'import'), at = head.place.at;
             if (value.hasVideo) head.place.at += value.frames;
-            const insert = {source: {kind: 'import', id: row.id}, at, frames: value.frames, hasVideo: value.hasVideo, hasAudio: value.hasAudio};
+            const insert = {source: {kind: 'import', id: row.id}, at, frames: value.frames, hasVideo: value.hasVideo, hasAudio: value.hasAudio, ...(!value.hasVideo && head.place.track ? {targetTrack: head.place.track, replace: head.place.replace === true} : {})};
             placed = placed.then(() => disposed ? null : actions.insertSource(insert, {loadMetadata: true})).catch(actions.error);
         }
     }
-    async function importFiles(files, {at} = {}) {
+    async function importFiles(files, {at, track, replace = false} = {}) {
         choose('import');
-        const place = Number.isSafeInteger(at) && at >= 0 ? {at} : null;
+        const place = Number.isSafeInteger(at) && at >= 0 ? {at, ...(['a1', 'a2', 'a3'].includes(track) ? {track, replace} : {})} : null;
         for (const value of files) {
             if (disposed) break;
             const id = 'upload-' + Math.random(), row = {id, name: value.name, kind: value.type.startsWith('audio') ? 'audio' : 'video', state: 'preparing', fraction: 0, sending: true};
diff --git a/web/editor_lifecycle.js b/web/editor_lifecycle.js
index 4054e097..561d2f67 100644
--- a/web/editor_lifecycle.js
+++ b/web/editor_lifecycle.js
@@ -7,7 +7,7 @@ export function discardEmptyEdit(record, initial, {busy = false, hasMedia = fals
         || record.tracks.some(track => track.clips.length) || record.replacements?.length) return false;
     // Compare settings, track controls and sparse project fields with initial().
     // An untouched empty second sound track does not make an edit differ from a new one.
-    const bare = track => track.id === 'a2' && !track.clips.length && Object.keys(track).every(key => ['id', 'kind', 'clips'].includes(key));
+    const bare = track => ['a2', 'a3'].includes(track.id) && !track.clips.length && Object.keys(track).every(key => ['id', 'kind', 'clips'].includes(key));
     const content = value => {
         const {id, revision, serial, name, ...rest} = value;
         return {...rest, tracks: rest.tracks.filter(track => !bare(track))};
diff --git a/web/editor_menu.js b/web/editor_menu.js
index 7bc6b847..e0420b3b 100644
--- a/web/editor_menu.js
+++ b/web/editor_menu.js
@@ -5,6 +5,7 @@ import {clickSelection, createSelectionActions, isTyping, selectedIds, playheadI
 const registered = new Set();
 // Groups appear in first-registration order; matching groups stay together.
 // Built-ins use 'edit' and 'split'. Return the disposer when unloading an extension.
+// visible(context), when given, leaves the item out of menus it does not belong in.
 // label/shortcut accept a string or (context) => string, so extensions can use context.t.
 export function registerMenuItem(item) {
     if (!['part', 'empty'].includes(item.where) || item.group == null || !item.label || typeof item.run !== 'function')
@@ -52,7 +53,7 @@ export function menuItems(context) {
     if (preview && context.actions.runSecondPass) items.push({group: 'generate', label: t('Run second pass', '继续二采'), shortcut: '',
         enabled: !context.actions.generationSending?.(), run: () => context.actions.runSecondPass(context.state.selection)});
     const value = field => typeof field === 'function' ? field(context) : field;
-    for (const item of registered) if (item.where === context.where) items.push({...item,
+    for (const item of registered) if (item.where === context.where && (!item.visible || item.visible(context))) items.push({...item,
         label: value(item.label), shortcut: value(item.shortcut) || '', enabled: item.enabled ? !!item.enabled(context) : true,
         run: () => item.run(context)});
     const groups = new Map();
diff --git a/web/editor_model.js b/web/editor_model.js
index 0678e2fb..3838930d 100644
--- a/web/editor_model.js
+++ b/web/editor_model.js
@@ -124,6 +124,7 @@ export function addAudioTrack(record) {
     const next = serialize(record);
     check(!next.tracks.some(track => track.id === 'a2'), 'track');
     next.tracks.push({id: 'a2', kind: 'audio', clips: []});
+    next.tracks.sort((a, b) => TRACK_ORDER.indexOf(a.id) - TRACK_ORDER.indexOf(b.id));
     return parse(next);
 }
 export function removeAudioTrack(record) {
@@ -148,11 +149,13 @@ export function parse(value) {
     const settings = jsonData(value.settings);
     check(JSON.stringify(settings).length <= 1024 * 1024, 'settings');
     check(Array.isArray(value.tracks) && value.tracks.length >= 2 && value.tracks.length <= RULES.maxTracks
-        && value.tracks.length !== 4 && value.tracks.length !== 5 && value.tracks.length !== 6, 'track');
+        && value.tracks.length !== 5 && value.tracks.length !== 6, 'track');
     const ids = new Set();
     const tracks = value.tracks.map((raw, index) => {
-        const id = ['v1', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6'][index], kind = index === 0 ? 'video' : 'audio';
+        // v1 and a1 by position; then an optional second sound track, the recording sub-track under a1 and the three separated-sound tracks, in that order.
+        const id = index < 2 ? ['v1', 'a1'][index] : object(raw) ? raw.id : null, kind = index === 0 ? 'video' : 'audio';
         check(object(raw) && raw.id === id && raw.kind === kind, 'track');
+        check(index < 2 || LATER_TRACKS.some(later => later.length === value.tracks.length - 2 && later[index - 2] === id), 'track');
         // The three tracks after a3 are the separated sound of one clip each: all of them or none.
         check(index < 4 ? raw.stem === undefined : raw.stem === STEM_TRACKS[index - 4], 'track');
         check(Array.isArray(raw.clips) && raw.clips.length <= RULES.maxClips, 'track');
@@ -344,8 +347,12 @@ function rollback(record, id, pending, reason = null) {
     tx.rolledBack = true;
     return finish(next);
 }
+const TRACK_ORDER = ['v1', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6'];
 function audioTrack(record, id = 'a1') {
-    if (!record.tracks.some(track => track.id === id)) record.tracks.push({id, kind: 'audio', clips: []});
+    if (!record.tracks.some(track => track.id === id)) {
+        record.tracks.push({id, kind: 'audio', clips: []});
+        record.tracks.sort((a, b) => TRACK_ORDER.indexOf(a.id) - TRACK_ORDER.indexOf(b.id));
+    }
     return trackBy(record, id);
 }
 const freshId = record => `c${++record.serial}`;
@@ -483,15 +490,27 @@ function storedSize(record) {
     return size;
 }
 // A saved video brings the description it was generated from; one that cannot be kept is left out.
-export function insertSource(record, {source, frames, hasVideo, hasAudio, width, height, at: position = 0, text = '', by = 'user', targetTrack}) {
+// Empties [start, start + frames) on one track by cutting the clips that cross its edges and removing what lies inside; the rest stays.
+function clearStretch(record, trackId, start, frames) {
+    let next = record;
+    for (const frame of [start, start + frames]) {
+        const hit = trackBy(next, trackId).clips.find(clip => clip.start < frame && end(clip) > frame);
+        if (hit) next = split(next, hit.id, frame);
+    }
+    const inside = trackBy(next, trackId).clips.filter(clip => clip.start >= start && end(clip) <= start + frames).map(clip => clip.id);
+    return inside.length ? remove(next, inside) : next;
+}
+export function insertSource(record, {source, frames, hasVideo, hasAudio, width, height, at: position = 0, text = '', by = 'user', targetTrack, replace = false}) {
     const given = source; source = sourceData(source); check(whole(frames, 1) && whole(position), 'range');
     check(typeof hasVideo === 'boolean' && typeof hasAudio === 'boolean' && (hasVideo || hasAudio), 'source');
     check(TEXT_BY.includes(by), 'text');
     const words = hasVideo && typeof text === 'string' && validText(text.trim()) ? text.trim() : '';
+    // A take that is recorded again over an older one replaces what it covers, at the same place as the picture.
+    if (replace && !hasVideo && targetTrack === 'a3' && record.tracks.some(row => row.id === 'a3')) record = clearStretch(record, 'a3', position, frames);
     const next = copy(record);
     if (hasVideo) followFirstSize(next, width, height);
     const explicitAudioTrack = !hasVideo && targetTrack !== undefined;
-    if (explicitAudioTrack) check(['a1', 'a2'].includes(targetTrack), 'track');
+    if (explicitAudioTrack) check(['a1', 'a2', 'a3'].includes(targetTrack), 'track');
     let track = explicitAudioTrack ? audioTrack(next, targetTrack) : trackBy(next, hasVideo ? 'v1' : 'a1');
     if (!hasVideo && !explicitAudioTrack && track.clips.some(clip => overlaps(clip, position, frames))) track = audioTrack(next, 'a2');
     check(!explicitAudioTrack || !track.locked, 'locked');
@@ -508,12 +527,14 @@ export function insertSource(record, {source, frames, hasVideo, hasAudio, width,
     }
     const result = finish(next);
     // The description is a convenience: a project it would make too large to save takes the video without it.
-    if (words && storedSize(result) > STORED_ROOM) return insertSource(record, {source: given, frames, hasVideo, hasAudio, width, height, at: position, targetTrack});
+    if (words && storedSize(result) > STORED_ROOM) return insertSource(record, {source: given, frames, hasVideo, hasAudio, width, height, at: position, targetTrack, replace});
     return result;
 }
 // The separated sound of an audio clip: three tracks after a2 hold one clip each (dialogue, music, ambience)
 // over the parent's range, and the parent goes silent. Deleting every stem clip gives the parent its volume back
 // (normalizeAudioEdits), so the silence needs no separate undo.
+// The tracks after a1, in order: a second sound track, the recording sub-track, and the separated sound that needs both.
+const LATER_TRACKS = [[], ['a2'], ['a3'], ['a2', 'a3'], ['a2', 'a3', 'a4', 'a5', 'a6']];
 export const STEM_TRACKS = Object.freeze(['dialogue', 'music', 'ambience']);
 export function placeStems(record, id, sources) {
     const next = copy(record), parent = find(next, id);
@@ -545,7 +566,7 @@ export function move(record, id, start, {targetTrack} = {}) {
     let track = trackOf(next, primary.id);
     // Only independent audio changes rows; linked pairs keep automatic routing.
     if (clips.length === 1 && track.kind === 'audio' && targetTrack !== undefined) {
-        check(['a1', 'a2'].includes(targetTrack), 'track');
+        check(['a1', 'a2', 'a3'].includes(targetTrack), 'track');
         assertUnlocked(record, [primary.id]);
         track = audioTrack(next, targetTrack);
         check(!track.locked, 'locked');
@@ -975,7 +996,7 @@ export function planRange(record, {start, frames, parts, target = 'both', text =
     if (!record.tracks.some(track => track.clips.some(clip => overlaps(clip, start, frames)))) frames = Math.max(RULES.minSeconds, Math.round(frames / FPS)) * FPS;
     const videoHits = trackBy(record, 'v1').clips.filter(clip => overlaps(clip, start, frames));
     const audioHits = trackBy(record, 'a1').clips.filter(clip => overlaps(clip, start, frames));
-    const otherHits = record.tracks.find(track => track.id === 'a2')?.clips.filter(clip => overlaps(clip, start, frames)) || [];
+    const otherHits = record.tracks.filter(track => track.id === 'a2' || track.id === 'a3').flatMap(track => track.clips.filter(clip => overlaps(clip, start, frames)));
     const hits = [...videoHits, ...audioHits];
     if (hits.length || otherHits.length) {
         check(hits.length > 0, 'unsupported');
diff --git a/web/editor_player.js b/web/editor_player.js
index 83d3ed1b..b10d2bfa 100644
--- a/web/editor_player.js
+++ b/web/editor_player.js
@@ -5,7 +5,7 @@ import {createPreviewPicture} from './editor_preview_picture.js';
 import {sourceKey, mediaURL} from './editor_store.js';
 import {clipPictureSize, createPictureGuide} from './editor_frame.js';
 import {createPlaybackClock} from './editor_transport_model.js';
-import {createAudioPreview} from './editor_audio.js';
+import {createAudioPreview, isOriginalSound} from './editor_audio.js';
 import {previewSpeed, speedAudioFrame, separateSpeedAudio} from './editor_speed.js';
 import {sourceFrame, percent} from './editor_speed_model.js';
 const el = (tag, cls) => { const e = document.createElement(tag); if (cls) e.className = cls; return e; };
@@ -48,7 +48,7 @@ export function createEditorPlayer(host, transport, {state, sources, api, t, err
     const picturePreview = createPreviewPicture(host, frame, {state, t});
     const playButton = el('button', 'fv-ed-play'); playButton.type = 'button'; playButton.title = t('Space', '空格');
     const time = el('span', 'fv-ed-time'); time.setAttribute('aria-live', 'off'); transport.append(playButton, time);
-    let active = 0, clipId = null, playing = false, disposed = false, raf = null, clockStart = 0, frameStart = 0, ticking = false, preview = null, previewSize = null, previewProject = null;
+    let active = 0, clipId = null, silenced = false, playing = false, disposed = false, raf = null, clockStart = 0, frameStart = 0, ticking = false, preview = null, previewSize = null, previewProject = null;
     let audioContext = null, textRenderer = null, chains = [], chainSignature = null, chainRequest = null, chainEpoch = 0;
     const failedChains = new Set(), entries = new Map();
     let seekGeneration = 0, forcePosition = false, pictureView = null, processedSound = false;
@@ -299,19 +299,19 @@ export function createEditorPlayer(host, transport, {state, sources, api, t, err
             clipId = clip.id;
         }
         const linked = hasPicture ? [...map.values()].find(row => row.clip.id === clip.link) : null;
-        const processedAudio = audioPreview.render({record, position, playing: playing && playback.rate > 0, playbackRate: playback.rate});
+        const processedAudio = audioPreview.render({record, position, playing: playing && playback.rate > 0, playbackRate: playback.rate, silenceOriginal: silenced});
         processedSound = !!processedAudio;
         // The joined sound is the plain forward path only: sound edits, changed speed and
         // backward playback keep their own routes and the original sound.
         const plainSpeed = id => !separateSpeedAudio(model.find(record, id));
-        const availableChains = processedAudio || playback.rate !== 1 ? [] : chains.filter(c => !failedChains.has(c.key) && c.clips.every(plainSpeed));
+        const availableChains = processedAudio || silenced || playback.rate !== 1 ? [] : chains.filter(c => !failedChains.has(c.key) && c.clips.every(plainSpeed));
         const selected = new Map([...map].filter(([track]) => track !== 'v1').map(([track, row]) =>
             [track, useChain(selectAudioChain(availableChains, track, row.clip, position, volumePreview), track)]));
         const linkedChain = linked && [...selected.values()].some(value => value?.chain.clips.includes(linked.clip.id));
         const originalSeparate = processedAudio || !!linked?.clip.splice || !hasPicture || separateSpeedAudio(linked?.clip);
         const separate = originalSeparate || linkedChain;
         if (hasPicture) {
-            const video = videos[active], speedPlayback = previewSpeed(video, clip, playing, linked?.clip); video.muted = !linked || separate || playback.rate < 0 || speedPlayback.muted;
+            const video = videos[active], speedPlayback = previewSpeed(video, clip, playing, linked?.clip); video.muted = !linked || separate || silenced || playback.rate < 0 || speedPlayback.muted;
             video._timelineClip = clip;
             delete video.dataset.preparedClip;
             seekMedia(video, mediaURL(api, source.video), (videoRow.frame + (playing && playback.rate > 0 ? 0 : .5)) / 24, speedPlayback.running && map.get('v1')?.clip.id === clip.id, clipVolume(linked?.clip));
@@ -336,7 +336,7 @@ export function createEditorPlayer(host, transport, {state, sources, api, t, err
             }
             if (carriedByVideo || slot >= audio.length) continue;
             const url = mediaURL(api, metadata.audio); if (!url) continue;
-            const media = audio[slot++], speed = previewSpeed(media, row.clip, playing); delete media.dataset.audioChain; media.muted = speed.muted;
+            const media = audio[slot++], speed = previewSpeed(media, row.clip, playing); delete media.dataset.audioChain; media.muted = speed.muted || silenced && isOriginalSound(row.clip);
             media._timelineClip = row.clip;
             seekMedia(media, url, audioSeconds(row.clip, speedAudioFrame(row.clip, shown - row.clip.start)), speed.running, clipVolume(row.clip));
         }
@@ -449,7 +449,9 @@ export function createEditorPlayer(host, transport, {state, sources, api, t, err
         else if ((row?.clip.id || null) !== clipId) render();
     });
     render();
-    return {element: frame, playback, picturePreview, play, pause, toggle: () => playing ? pause() : play(), refresh: render,
+    return {element: frame, playback, picturePreview, play, pause,
+        // While a take is recorded the picture's own sound stays off, so the microphone does not pick it up.
+        silenceOriginal(on) { if (silenced === !!on) return; silenced = !!on; resetEntries(); forcePosition = true; render(); }, toggle: () => playing ? pause() : play(), refresh: render,
         clearPreview() { clearPreview(); render(); },
         get playing() { return playing; },
         setTextRenderer(callback) { textRenderer = callback; },
diff --git a/web/editor_record.css b/web/editor_record.css
new file mode 100644
index 00000000..a0c1b057
--- /dev/null
+++ b/web/editor_record.css
@@ -0,0 +1,43 @@
+.fv-ed-record{grid-column:1/-1;grid-row:4;z-index:8;box-sizing:border-box;display:grid;grid-template-columns:minmax(0,1fr) auto minmax(0,1fr);align-items:center;column-gap:16px;min-height:60px;padding:10px 16px;border-top:1px solid var(--fv-border);border-bottom:1px solid var(--fv-border);background:var(--fv-card);color:var(--fv-ink);font:13px/1.4 var(--fv-font,system-ui);min-width:0}
+.fv-ed-record[hidden]{display:none}
+.fv-ed-record-side{display:flex;min-width:0}
+.fv-ed-record-center{display:flex;align-items:center;gap:14px;min-width:0}
+.fv-ed-record-close{justify-self:end}
+.fv-ed-record-device{appearance:none;flex:0 1 auto;width:auto;max-width:min(100%,260px);height:32px;padding:0 12px;border:1px solid var(--fv-border);border-radius:16px;background:var(--fv-card);color:var(--fv-muted);font:inherit;text-overflow:ellipsis;cursor:pointer}
+.fv-ed-record-device:hover:not(:disabled){color:var(--fv-ink)}
+.fv-ed-record-device:disabled{opacity:.5;cursor:default}
+/* The level is a row of dots that is always drawn, so it reads as a meter before anything is said; the lit part follows the voice. */
+.fv-ed-record-meter{flex:0 0 132px;height:8px;overflow:hidden;background:color-mix(in srgb,var(--fv-ink) 16%,transparent);-webkit-mask:repeating-linear-gradient(90deg,#000 0 4px,transparent 4px 8px);mask:repeating-linear-gradient(90deg,#000 0 4px,transparent 4px 8px)}
+.fv-ed-record-level{width:100%;height:100%;background:var(--fv-accent);transform:scaleX(0);transform-origin:left;transition:transform .08s linear}
+.fv-editor .fv-ed-record .fv-ed-record-main{flex:none;display:inline-flex;align-items:center;gap:8px;height:36px;padding:0 18px 0 14px;border:1px solid color-mix(in srgb,var(--fv-danger,#d33) 55%,transparent);border-radius:18px;background:color-mix(in srgb,var(--fv-danger,#d33) 12%,var(--fv-card));color:var(--fv-ink);font:inherit;font-weight:var(--fv-semibold,600);cursor:pointer}
+.fv-ed-record-main::before{content:"";width:10px;height:10px;border-radius:50%;background:var(--fv-danger,#d33)}
+.fv-editor .fv-ed-record .fv-ed-record-main:hover:not(:disabled){background:color-mix(in srgb,var(--fv-danger,#d33) 20%,var(--fv-card))}
+.fv-editor .fv-ed-record[data-phase=recording] .fv-ed-record-main,.fv-editor .fv-ed-record[data-phase=counting] .fv-ed-record-main,.fv-editor .fv-ed-record[data-phase=saving] .fv-ed-record-main{border-color:transparent;background:#e5484d;color:#fff}
+.fv-ed-record:is([data-phase=recording],[data-phase=counting],[data-phase=saving]) .fv-ed-record-main::before{width:9px;height:9px;border-radius:2px;background:#fff}
+.fv-ed-record[data-phase=recording] .fv-ed-record-main::before{animation:fv-ed-record-pulse 1.2s ease-in-out infinite}
+.fv-editor .fv-ed-record .fv-ed-record-main:disabled{border-color:transparent;background:color-mix(in srgb,var(--fv-ink) 12%,transparent);color:var(--fv-muted);cursor:not-allowed}
+.fv-ed-record-main:disabled::before{background:var(--fv-muted)}
+.fv-ed-record-note{min-width:2.4em;color:var(--fv-muted);font-variant-numeric:tabular-nums;overflow-wrap:anywhere}
+.fv-ed-record[data-phase=counting] .fv-ed-record-note{color:var(--fv-ink);font-size:22px;font-weight:var(--fv-semibold,600);line-height:1}
+.fv-ed-record[data-phase=recording] .fv-ed-record-note{color:var(--fv-ink);font-size:15px}
+.fv-editor .fv-ed-record .fv-ed-record-close{flex:none;width:28px;height:28px;border:0;border-radius:6px;background:transparent;color:var(--fv-muted);font-size:18px;line-height:1;cursor:pointer}
+.fv-ed-record-close:hover{background:color-mix(in srgb,var(--fv-ink) 10%,transparent)}
+@keyframes fv-ed-record-pulse{50%{opacity:.45}}
+@keyframes fv-ed-record-land{from{box-shadow:0 0 0 3px var(--fv-accent)}to{box-shadow:0 0 0 3px transparent}}
+.fv-ed-clip[data-landed=true]{animation:fv-ed-record-land 1.4s ease-out}
+@media (prefers-reduced-motion:reduce){.fv-ed-record-main::before,.fv-ed-clip[data-landed=true]{animation:none!important}.fv-ed-record-level{transition:none}}
+@media (max-width:760px){
+ .fv-ed-record{grid-column:1;grid-template-columns:minmax(0,1fr) auto;row-gap:8px;padding:10px 12px}
+ .fv-ed-record-center{grid-column:1;grid-row:1;gap:10px}
+ .fv-ed-record-close{grid-column:2;grid-row:1}
+ .fv-ed-record-side{grid-column:1/-1;grid-row:2}
+ .fv-ed-record-side:has(.fv-ed-record-device[hidden]){display:none}
+ .fv-ed-record-meter{flex:1 1 48px;min-width:48px}
+}
+
+/* The recording sub-track sits one level under a1, with the same head as the other sound tracks. */
+.fv-ed-track-row[data-sub=true] .fv-ed-track-empty{opacity:.8}
+/* The bar takes the generation bar's place while it is open, so the row is only as tall as the bar. */
+.fv-studio.fv-editor:has(.fv-ed-record:not([hidden])) .fv-ed-genbar{display:none}
+.fv-ed-audio-track-switch:disabled{opacity:.35;cursor:default}
+.fv-ed-record-meter[hidden]{display:none}
diff --git a/web/editor_record.js b/web/editor_record.js
new file mode 100644
index 00000000..3c75b721
--- /dev/null
+++ b/web/editor_record.js
@@ -0,0 +1,189 @@
+// Recording from the microphone onto a sound track. A small bar above the tracks holds the microphone choice, the level,
+// and the start/stop button; the take is saved as a WAV and placed like any imported sound, never over what is already there.
+import {registerMenuItem} from './editor_menu.js';
+import {COUNTDOWN_SECONDS, elapsedText, deviceName, recordable, recordRange, landingTrack, replacesTake, secondsOf, takeName, level, mixdown, encodeWav} from './editor_record_model.js';
+const el = (tag, cls, text) => { const node = document.createElement(tag); if (cls) node.className = cls; if (text != null) node.textContent = text; return node; };
+let styled = false;
+function styles() {
+    if (styled) return; styled = true;
+    const link = el('link'); link.rel = 'stylesheet'; link.href = new URL('./editor_record.css', import.meta.url).href; document.head.append(link);
+}
+const MIC_PATH = 'M8 1.5a2.5 2.5 0 0 0-2.5 2.5v4a2.5 2.5 0 0 0 5 0V4A2.5 2.5 0 0 0 8 1.5M3.5 7.5a4.5 4.5 0 0 0 9 0M8 12v2.5M5.5 14.5h5';
+
+export function createEditorRecord({state, player, library, t, error = () => {}, notify = () => {}, bar: host, button: toolbarButton}) {
+    styles();
+    const bar = el('div', 'fv-ed-record'); bar.hidden = true; bar.setAttribute('role', 'group'); bar.setAttribute('aria-label', t('Record', '录音'));
+    const devices = el('select', 'fv-ed-record-device'); devices.setAttribute('aria-label', t('Microphone', '麦克风')); devices.hidden = true;
+    const meter = el('div', 'fv-ed-record-meter'), fill = el('div', 'fv-ed-record-level'); meter.append(fill); meter.setAttribute('aria-hidden', 'true');
+    const main = el('button', 'fv-ed-record-main', t('Start recording', '开始录音')); main.type = 'button';
+    const note = el('span', 'fv-ed-record-note'); note.setAttribute('role', 'status');
+    const close = el('button', 'fv-ed-record-close', '×'); close.type = 'button'; close.setAttribute('aria-label', t('Close', '关闭'));
+    const side = el('div', 'fv-ed-record-side'), center = el('div', 'fv-ed-record-center');
+    side.append(devices); center.append(main, meter, note); bar.append(side, center, close);
+
+    let phase = 'idle', denied = false, stream = null, recorder = null, chunks = [], context = null, frame = null, timers = [], disposed = false, session = 0, ticker = null, listening = null, startedAt = 0;
+    const clear = () => { timers.forEach(clearTimeout); timers = []; clearInterval(ticker); ticker = null; };
+    // The level moves only while the bar is open: the microphone is listened to from opening until closing, and the take reuses that stream.
+    const release = () => {
+        cancelAnimationFrame(frame); frame = null; listening = null;
+        stream?.getTracks().forEach(track => track.stop()); stream = null; context?.close().catch(() => {}); context = null; fill.style.transform = 'scaleX(0)';
+    };
+    // One request at a time: a quick second choice of microphone waits for the first, then replaces its stream.
+    let queue = Promise.resolve();
+    const listen = () => queue = queue.then(listening_);
+    async function listening_() {
+        if (disposed || bar.hidden) return false;
+        if (stream && listening === devices.value) return true;
+        release();
+        const mine = session;
+        try {
+            const next = await media().getUserMedia({audio: devices.value ? {deviceId: {exact: devices.value}} : true});
+            if (mine !== session || disposed || bar.hidden) { next.getTracks().forEach(track => track.stop()); return false; }
+            stream = next; listening = devices.value; context = new AudioContext();
+            const analyser = context.createAnalyser(); analyser.fftSize = 1024;
+            context.createMediaStreamSource(stream).connect(analyser);
+            const block = new Float32Array(analyser.fftSize);
+            const loop = () => { analyser.getFloatTimeDomainData(block); fill.style.transform = `scaleX(${level(block)})`; frame = requestAnimationFrame(loop); };
+            loop(); return true;
+        } catch { return false; }
+    }
+    function paint() {
+        main.textContent = phase === 'idle' ? t('Start recording', '开始录音') : t('Stop', '停止');
+        main.disabled = denied && phase === 'idle'; meter.hidden = main.disabled; devices.disabled = phase !== 'idle';
+        bar.dataset.phase = phase;
+        toolbarButton?.setAttribute('aria-pressed', String(!bar.hidden));
+    }
+    const say = text => { note.textContent = text; };
+    const denial = () => { denied = true; say(t('Microphone access was not granted.', '未获得麦克风权限。')); paint(); };
+    const media = () => globalThis.navigator?.mediaDevices;
+
+    // Opening the bar asks for the microphone once, so the choice of devices can carry their names.
+    async function probe() {
+        const mine = ++session;
+        try {
+            if (!media()?.getUserMedia) throw new Error('unavailable');
+            if (!await listen()) throw new Error('denied');
+            if (mine !== session || disposed) return;
+            denied = false; say('');
+            const all = (await media().enumerateDevices()).filter(device => device.kind === 'audioinput');
+            // Chrome lists the default and communications choices again under the real device's name: they are left out when a real one exists.
+            const real = all.filter(device => !['default', 'communications'].includes(device.deviceId)), inputs = real.length ? real : all.slice(0, 1);
+            devices.replaceChildren(...inputs.map((device, index) => { const option = el('option', null, deviceName(device.label, index + 1, t)); option.value = device.deviceId; return option; }));
+            devices.hidden = inputs.length < 2;
+            // The stream was opened on the system default: show the real device behind it, or open the one shown when none is known.
+            const behind = all.find(device => device.deviceId === 'default' && device.groupId);
+            const match = behind && inputs.find(device => device.groupId === behind.groupId);
+            if (match) devices.value = match.deviceId;
+            if (stream) listening = match || inputs.length < 2 ? devices.value : null;
+            if (stream && listening === null) await listen();
+            paint();
+        } catch { if (mine === session && !disposed) denial(); }
+    }
+    function open() {
+        if (disposed || !bar.hidden) return;
+        bar.hidden = false; denied = false; say(''); paint(); probe();
+    }
+    function hide() {
+        if (phase !== 'idle') abort();
+        session++; bar.hidden = true; release(); paint();
+    }
+    function abort() {
+        clear(); if (recorder && recorder.state !== 'inactive') { recorder.ondataavailable = recorder.onstop = null; try { recorder.stop(); } catch { /* already stopped */ } }
+        recorder = null; chunks = []; player.silenceOriginal?.(false); player.pause?.(); phase = 'idle'; say(''); paint();
+    }
+
+    async function begin() {
+        if (phase !== 'idle' || denied) return;
+        const selection = state.selection, range = recordRange(selection, state.playhead);
+        if (!landingTrack(state.record, selection, range.start, range.frames ?? 1)) {
+            say(t('The recording track is locked.', '录音轨已锁定。')); return;
+        }
+        const mine = ++session;
+        phase = 'counting'; paint();
+        if (!await listen()) { if (mine === session) { phase = 'idle'; denial(); } return; }
+        if (mine !== session || disposed) return;
+        // The count runs before the take, so the speaker has a moment to get ready.
+        let left = COUNTDOWN_SECONDS;
+        const tick = () => {
+            if (mine !== session) return;
+            if (left > 0) { say(String(left--)); timers.push(setTimeout(tick, 1000)); } else go(range, mine, selection);
+        };
+        tick();
+    }
+    function go(range, mine, selection) {
+        phase = 'recording'; paint(); startedAt = performance.now(); say(elapsedText(0));
+        ticker = setInterval(() => say(elapsedText((performance.now() - startedAt) / 1000)), 250);
+        recorder = new MediaRecorder(stream); chunks = [];
+        recorder.ondataavailable = event => { if (event.data.size) chunks.push(event.data); };
+        recorder.onstop = () => finish(range, mine, selection);
+        state.seek(range.start); player.silenceOriginal?.(true);
+        recorder.start(); player.play?.();
+        if (range.frames) timers.push(setTimeout(stop, Math.ceil(secondsOf(range.frames) * 1000)));
+    }
+    function stop() {
+        if (phase === 'counting') { abort(); return; }
+        if (phase !== 'recording') return;
+        clear(); phase = 'saving'; paint(); say(t('Saving…', '正在保存…'));
+        player.pause?.(); player.silenceOriginal?.(false);
+        if (recorder.state !== 'inactive') recorder.stop();
+    }
+    async function finish(range, mine, selection) {
+        const blob = new Blob(chunks, {type: recorder?.mimeType || 'audio/webm'}); chunks = []; recorder = null;
+        let file = null, frames = 0;
+        try {
+            const decoder = new AudioContext(), decoded = await decoder.decodeAudioData(await blob.arrayBuffer()); decoder.close().catch(() => {});
+            const limit = range.frames ? Math.round(secondsOf(range.frames) * decoded.sampleRate) : Infinity;
+            const samples = mixdown(Array.from({length: decoded.numberOfChannels}, (_, index) => decoded.getChannelData(index)), limit);
+            frames = Math.min(range.frames ?? Infinity, Math.ceil(samples.length / decoded.sampleRate * 24));
+            if (samples.length) file = new File([encodeWav(samples, decoded.sampleRate)], takeName(new Date(), t), {type: 'audio/wav'});
+        } catch (value) { error(value); }
+        if (disposed || mine !== session) return;
+        phase = 'idle'; say(''); paint();
+        if (!file) { notify(t('Nothing was recorded.', '没有录到声音。')); return; }
+        bar.hidden = true; release(); paint();
+        const before = new Set(state.record.tracks.flatMap(item => item.clips.map(clip => clip.id)));
+        const track = landingTrack(state.record, selection, range.start, frames) ?? undefined, replace = track === 'a3' && replacesTake(state.record, range.start, frames);
+        await library.importFiles([file], {at: range.start, track, replace: track === 'a3'});
+        land(before);
+        if (replace) notify(t('Replaced the earlier recording in this range.', '已替换这一段原有的录音。'));
+    }
+    // The clip just placed settles in with a short highlight, so the eye follows the take from the bar to the track.
+    function land(before) {
+        const until = performance.now() + 15000, fresh = () => state.record.tracks.flatMap(item => item.clips).filter(clip => !before.has(clip.id)).map(clip => clip.id);
+        let shown = 0;
+        // The timeline redraws on its own schedule, so the mark is put on each frame until the highlight has run.
+        const mark = () => {
+            const nodes = fresh().flatMap(id => [...document.querySelectorAll(`.fv-ed-clip[data-clip="${CSS.escape(id)}"]`)]);
+            if (nodes.length && !shown) shown = performance.now();
+            for (const node of nodes) node.dataset.landed = 'true';
+            if (performance.now() < (shown ? shown + 1400 : until)) requestAnimationFrame(mark);
+            else for (const node of document.querySelectorAll('.fv-ed-clip[data-landed]')) delete node.dataset.landed;
+        };
+        requestAnimationFrame(mark);
+    }
+    // R starts and stops while the bar is open; Esc cancels a take in progress, then closes the bar.
+    const typing = target => target?.closest?.('input, textarea, [contenteditable=true]');
+    // Called by the editor's key router; true when the key was taken.
+    function keys(event) {
+        if (event.type !== 'keydown' || bar.hidden || event.isComposing || event.ctrlKey || event.metaKey || event.altKey || typing(event.target)) return false;
+        const key = event.key.toLowerCase();
+        if (key === 'escape') {
+            event.preventDefault(); if (phase !== 'idle') abort(); else hide(); return true;
+        }
+        if (key === 'r' && !event.target?.closest?.('select') && !event.repeat) { event.preventDefault(); main.onclick(); return true; }
+        return false;
+    }
+    devices.onchange = () => { if (!bar.hidden && phase === 'idle') listen(); };
+    main.onclick = () => phase === 'idle' ? begin() : stop();
+    close.onclick = hide;
+    if (toolbarButton) toolbarButton.onclick = () => bar.hidden ? open() : hide();
+
+    // The menu entry sits on the sound tracks, where an empty spot or a stretch chosen can take a recording.
+    const unregister = registerMenuItem({where: 'empty', group: 'sound', label: context => context.t('Record', '录音'),
+        visible: context => !context.track || ['a1', 'a2'].includes(context.track), run: () => open()});
+    const unsubscribe = state.subscribe(event => { if (event.type === 'selection' && toolbarButton) toolbarButton.hidden = !recordable(state.selection); });
+    if (toolbarButton) toolbarButton.hidden = !recordable(state.selection);
+    paint();
+    return {element: bar, open, hide, keyboard: keys, get phase() { return phase; }, dispose() { disposed = true; unregister(); unsubscribe(); abort(); release(); bar.remove(); }};
+}
+export const RECORD_ICON = MIC_PATH;
diff --git a/web/editor_record_model.js b/web/editor_record_model.js
new file mode 100644
index 00000000..a74d3689
--- /dev/null
+++ b/web/editor_record_model.js
@@ -0,0 +1,84 @@
+// Recording from a microphone onto the sound tracks. Pure helpers: where a take starts and stops,
+// the 16-bit WAV a take is saved as (the server tells sound from picture by file suffix), the level shown while recording.
+import {FPS} from './editor_model.js';
+
+export const COUNTDOWN_SECONDS = 3;
+const AUDIO_TRACKS = ['a1', 'a2', 'a3'];
+
+// Whether the chosen stretch is on a sound track (a stretch of the picture track does not offer recording).
+export function recordable(selection) {
+    if (!selection) return true;
+    if (selection.kind === 'gap') return AUDIO_TRACKS.includes(selection.track);
+    if (selection.kind === 'range') return !selection.tracks?.length || selection.tracks.some(id => AUDIO_TRACKS.includes(id));
+    return false;
+}
+
+// A stretch chosen starts the take at its start and ends it at its end; with none, the take starts at the play position and runs until stopped.
+export function recordRange(selection, playhead) {
+    if (selection && ['gap', 'range'].includes(selection.kind) && Number.isSafeInteger(selection.start) && selection.frames > 0)
+        return {start: selection.start, frames: selection.frames};
+    return {start: Math.max(0, Math.round(playhead) || 0), frames: null};
+}
+
+// The sound track a take lands on: a1 when its stretch is free, otherwise the recording sub-track a3 under it, where
+// it replaces whatever an older take covers there. Null only when a3 is locked: a take never lands on the music track a2.
+export function landingTrack(record, selection, start, frames) {
+    const free = (track, ignoreLock) => !track || ((ignoreLock || !track.locked) && !track.clips.some(clip => clip.start < start + frames && start < clip.start + clip.frames));
+    const a1 = record.tracks.find(row => row.id === 'a1'), a3 = record.tracks.find(row => row.id === 'a3');
+    return free(a1) ? 'a1' : a3?.locked ? null : 'a3';
+}
+
+// Whether a take on the sub-track would cover part of an older take.
+export function replacesTake(record, start, frames) {
+    return !!record.tracks.find(row => row.id === 'a3')?.clips.some(clip => clip.start < start + frames && start < clip.start + clip.frames);
+}
+
+export const secondsOf = frames => frames / FPS;
+
+// A take's name in the library: 录音 / Recording and the time it began.
+export function takeName(date, t = en => en) {
+    const pad = value => String(value).padStart(2, '0');
+    return `${t('Recording', '录音')} ${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}.wav`;
+}
+
+// Loudness of a block of samples, 0 to 1, for the level meter.
+export function level(samples) {
+    if (!samples?.length) return 0;
+    let sum = 0;
+    for (let i = 0; i < samples.length; i++) sum += samples[i] * samples[i];
+    return Math.min(1, Math.sqrt(sum / samples.length) * 3);
+}
+
+// Mono mix of channel arrays, trimmed to `limit` samples when given.
+export function mixdown(channels, limit = Infinity) {
+    const length = Math.min(limit, Math.max(0, ...channels.map(channel => channel.length)));
+    const out = new Float32Array(length);
+    for (const channel of channels) for (let i = 0; i < length && i < channel.length; i++) out[i] += channel[i] / channels.length;
+    return out;
+}
+
+// 16-bit PCM mono WAV bytes.
+export function encodeWav(samples, sampleRate) {
+    if (!Number.isInteger(sampleRate) || sampleRate <= 0) throw new RangeError('sampleRate');
+    const bytes = new Uint8Array(44 + samples.length * 2), view = new DataView(bytes.buffer);
+    const text = (at, value) => { for (let i = 0; i < value.length; i++) view.setUint8(at + i, value.charCodeAt(i)); };
+    text(0, 'RIFF'); view.setUint32(4, 36 + samples.length * 2, true); text(8, 'WAVE'); text(12, 'fmt ');
+    view.setUint32(16, 16, true); view.setUint16(20, 1, true); view.setUint16(22, 1, true);
+    view.setUint32(24, sampleRate, true); view.setUint32(28, sampleRate * 2, true); view.setUint16(32, 2, true); view.setUint16(34, 16, true);
+    text(36, 'data'); view.setUint32(40, samples.length * 2, true);
+    for (let i = 0; i < samples.length; i++) {
+        const value = Math.max(-1, Math.min(1, samples[i]));
+        view.setInt16(44 + i * 2, value < 0 ? value * 0x8000 : value * 0x7fff, true);
+    }
+    return bytes;
+}
+
+// The elapsed time of a take, as m:ss.
+export const elapsedText = seconds => `${Math.floor(Math.max(0, seconds) / 60)}:${String(Math.floor(Math.max(0, seconds) % 60)).padStart(2, '0')}`;
+
+// A microphone by a short name: the system's default marker and the hardware id in brackets are dropped; a name that is empty or
+// only an id falls back to the number.
+export function deviceName(label, number, t) {
+    const name = String(label || '').replace(/^(default|communications)\s*-\s*/i, '').replace(/\s*\([0-9a-f]{4}:[0-9a-f]{4}\)\s*$/i, '').trim();
+    return name || t(`Microphone ${number}`, `麦克风 ${number}`);
+}
diff --git a/web/editor_text_model.js b/web/editor_text_model.js
index 7ed10595..790e1090 100644
--- a/web/editor_text_model.js
+++ b/web/editor_text_model.js
@@ -7,7 +7,9 @@ export const SUBTITLE_DEFAULTS = Object.freeze({font: 'sans', size: 44 / 1080, c
 export const isText = clip => ['text', 'subtitle'].includes(clip?.text_kind);
 export const isTextTrack = track => ['text', 'subtitle'].includes(track?.kind);
 export const hasTextData = record => record?.subtitle_style !== undefined || record?.tracks?.some(isTextTrack);
-export const displayTracks = record => [...record.tracks.filter(t => t.kind === 'subtitle'), ...record.tracks.filter(t => t.kind === 'text'), ...record.tracks.filter(t => !isTextTrack(t))];
+// The recording sub-track (a3) is drawn directly under a1.
+const media = rows => { const sub = rows.find(t => t.id === 'a3'); return sub ? rows.filter(t => t !== sub).flatMap(t => t.id === 'a1' ? [t, sub] : [t]) : rows; };
+export const displayTracks = record => [...record.tracks.filter(t => t.kind === 'subtitle'), ...record.tracks.filter(t => t.kind === 'text'), ...media(record.tracks.filter(t => !isTextTrack(t)))];
 export const defaults = kind => kind === 'subtitle' ? SUBTITLE_DEFAULTS : TEXT_DEFAULTS;
 export const styleOf = (record, clip) => ({...defaults(clip.text_kind), ...(clip.text_kind === 'subtitle' ? record.subtitle_style : clip.text_style)});
 const check = (ok, code = 'text') => { if (!ok) throw new model.EditError(code); };
diff --git a/web/editor_tracks.js b/web/editor_tracks.js
index 654a52ff..3bd93347 100644
--- a/web/editor_tracks.js
+++ b/web/editor_tracks.js
@@ -222,7 +222,7 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
     };
     const audioTargetAt = (source, event) => {
         const track = pointerTrackAt(event);
-        return !source.hasVideo && source.hasAudio && ['a1', 'a2'].includes(track) ? track : undefined;
+        return !source.hasVideo && source.hasAudio && ['a1', 'a2', 'a3'].includes(track) ? track : undefined;
     };
     const sourceInfo = key => typeof sources === 'function' ? sources(key) : sources.get?.(key) || sources[key];
     // The snapping switch lives in the transport model: it empties the point list (and Alt flips it per gesture).
@@ -500,8 +500,8 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
         const STEM_NAMES = {dialogue: t('Dialogue', '人声'), music: t('Music', '音乐'), ambience: t('Ambience', '环境声')};
         let top = 24, parted = false;
         for (const track of tracks) {
-            const name = track.kind === 'text' ? t('Text', '文字') : track.kind === 'subtitle' ? t('Subtitles', '字幕') : track.kind === 'video' ? t('Video', '画面') : track.stem ? STEM_NAMES[track.stem] : twoAudio
-                ? t(`Audio ${track.id.slice(1)}`, `声音 ${track.id.slice(1)}`) : t('Audio', '声音');
+            const name = track.kind === 'text' ? t('Text', '文字') : track.kind === 'subtitle' ? t('Subtitles', '字幕') : track.kind === 'video' ? t('Video', '画面') : track.stem ? STEM_NAMES[track.stem] : track.id === 'a3'
+                ? t('Voice', '录音') : twoAudio ? t(`Audio ${track.id.slice(1)}`, `声音 ${track.id.slice(1)}`) : t('Audio', '声音');
             let row = rows.get(track.id);
             if (!row) {
                 const node = create('div', 'fv-ed-track-row'); node.dataset.track = track.id;
@@ -518,6 +518,7 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
             // separated music lane where new music replaces the old.
             const tourId = track.stem === 'music' ? 'audio-music-stem' : track.stem ? '' : {a1: 'audio-a1-track', a2: 'audio-a2-track'}[track.id] || '';
             if (tourId) row.element.dataset.tourId = tourId; else delete row.element.dataset.tourId;
+            row.head.dataset.sub = row.element.dataset.sub = String(track.id === 'a3');
             row.empty.hidden = track.clips.length > 0;
             // A picture track with any block description grows a strip for it under the pictures.
             const noted = !!actions.describedTrack?.(track); row.element.dataset.noted = String(noted);
@@ -838,8 +839,8 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
             const result = moveParameters(gesture.clip, gesture.anchor, frame, dragPoints(desired, gesture.clip.frames), state.zoom);
             result.track = isText(gesture.clip) ? pointerHit(event).track : null;
             const pointedTrack = pointerTrackAt(event);
-            result.targetTrack = gesture.ids.length === 1 && ['a1', 'a2'].includes(gesture.track)
-                && ['a1', 'a2'].includes(pointedTrack) ? pointedTrack : undefined;
+            result.targetTrack = gesture.ids.length === 1 && ['a1', 'a2', 'a3'].includes(gesture.track)
+                && ['a1', 'a2', 'a3'].includes(pointedTrack) ? pointedTrack : undefined;
             gesture.result = result;
             const track = state.record.tracks.find(row => row.id === (result.targetTrack || gesture.track));
             const drop = isText(gesture.clip) ? {hit: false} : insertionPoint(track.clips, result.frame, gesture.ids);
@@ -1127,7 +1128,7 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
             if (draggedSource) try {
                 const preview = model.insertSource(state.record, {...draggedSource, at: frame.frame, targetTrack: audioTargetAt(draggedSource, event)});
                 const added = previewSourcePlacement(preview), sound = added.find(item => item.track !== 'v1');
-                const name = sound ? preview.tracks.length === 3
+                const name = sound ? !preview.tracks.some(track => track.id === 'a3') && preview.tracks.length === 3
                     ? t(`Audio ${sound.track === 'a1' ? 1 : 2}`, `声音 ${sound.track === 'a1' ? 1 : 2}`) : t('Audio', '声音') : '';
                 dropPoint = {frame: added[0].clip.start, label: `${clock(added[0].clip.start)} – ${clock(added[0].clip.start + draggedSource.frames)}${name ? ` · ${name}` : ''}`};
             } catch (error) {

From 4c1c6246285cd4f260c2b31e1453af1a08a85ace Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:35:46 +0000
Subject: [PATCH 23/26] Page check lists the recording scripts

---
 web/health.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/health.js b/web/health.js
index e2bbb306..1e25a644 100644
--- a/web/health.js
+++ b/web/health.js
@@ -14,7 +14,7 @@ const t = (en, zh) => cn ? zh : en;
 const launchVisit = query.get('freevideo') === 'launch';
 // Every script this folder ships; a test keeps the list in step with web/*.js.
 export const MODULES = ['audio_original.js', 'chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_confirm_settings.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'chain_rules.js', 'timed_prompt.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
-    'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_stems.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
+    'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_duration.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_stems.js', 'editor_record.js', 'editor_record_model.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_music.js', 'editor_music_model.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'image_lora.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_sections.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js', 'task_groups.js',
     'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'pass_mode.js','setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'other_usage.js', 'studio_queue.js', 'studio_size.js',

From 474ec192115c5e2be900f65e51b95524f1536c19 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:49:19 +0000
Subject: [PATCH 24/26] Editor: allow the separated-sound track layout (a2 to
 a6) when saving and opening projects

---
 freevideo_engine/comfy_editor.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/freevideo_engine/comfy_editor.py b/freevideo_engine/comfy_editor.py
index abde3549..7db24c3d 100644
--- a/freevideo_engine/comfy_editor.py
+++ b/freevideo_engine/comfy_editor.py
@@ -191,7 +191,7 @@ def bounded(value, depth=0):
     if not isinstance(raw_tracks, list) or len(raw_tracks) not in (2, 3, 4, 7):
         raise ValueError('Invalid tracks')
     later = [raw.get('id') if isinstance(raw, dict) else None for raw in raw_tracks[2:]]
-    if later not in ([], ['a2'], ['a3'], ['a2', 'a3']):
+    if later not in ([], ['a2'], ['a3'], ['a2', 'a3'], ['a2', 'a3', 'a4', 'a5', 'a6']):
         raise ValueError('Invalid tracks')
     expected = [('v1', 'video'), ('a1', 'audio')] + [(track_id, 'audio') for track_id in later]
     tracks, seen = [], {}

From 92ff0e871e47ac6bdb828b19174195fca31dec84 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 01:51:44 +0000
Subject: [PATCH 25/26] Audio cards: Use as is stays clickable under Preview
 first or a continued video

Audio cards: Use as is stays clickable under Preview first or a continued video; a click turns the preview off with a one-line note in the audio card, and a continuation says why it cannot
---
 scripts/test_freevideo_entry.mjs |  4 ++--
 web/audio_original.css           |  4 ++++
 web/audio_original.js            | 32 +++++++++++++++++++++++++-------
 web/freevideo.js                 | 32 ++++++++++++++++++++++++++++----
 web/studio.js                    |  4 ++--
 5 files changed, 61 insertions(+), 15 deletions(-)

diff --git a/scripts/test_freevideo_entry.mjs b/scripts/test_freevideo_entry.mjs
index 6c6e6f7b..b9aacb79 100644
--- a/scripts/test_freevideo_entry.mjs
+++ b/scripts/test_freevideo_entry.mjs
@@ -99,7 +99,7 @@ test('main browser entry registers both views and preserves node hooks', async t
         shareButton: () => new Element('button'), reportFileName: () => 'FreeVideo-report-20261008-101530.json',
         rememberPromptDraft() {}, savePromptDraft: async () => false, openImageEditor: async () => null, icon: () => '',
         AUDIO_USE: {reference: 'reference', original: 'original'}, usesOriginal: row => row?.use === 'original', checkOriginal: async () => ({ok: true}),
-        checkedLength: () => null, failureText: () => '', multipleText: () => '', createUseSwitch: () => globalThis.document.createElement('div'), originalBlocked: () => false,
+        checkedLength: () => null, failureText: () => '', multipleText: () => '', createUseSwitch: () => globalThis.document.createElement('div'), originalBlocked: () => false, stuckText: () => '', liftBlock: () => ({ok: true, note: ''}),
     };
     const previous = new Map();
     for (const [name, value] of Object.entries({
@@ -151,7 +151,7 @@ test('main browser entry registers both views and preserves node hooks', async t
             .replace("import { agentInterfaceState } from './agent_connect.js';", "const agentInterfaceState = async () => 'off';")
             .replace("import { installNativeErrorGuard } from './native_errors.js';", 'const installNativeErrorGuard = () => {};')
             .replace("import { installTranslateGuard } from './translate_guard.js';", 'const installTranslateGuard = () => {};')
-            .replace("import { AUDIO_USE, usesOriginal, checkOriginal, checkedLength, failureText, multipleText, createUseSwitch, originalBlocked } from './audio_original.js';", 'const {AUDIO_USE,usesOriginal,checkOriginal,checkedLength,failureText,multipleText,createUseSwitch,originalBlocked} = globalThis.__freevideoEntryTest;');
+            .replace("import { AUDIO_USE, usesOriginal, checkOriginal, checkedLength, failureText, multipleText, createUseSwitch, originalBlocked, stuckText, liftBlock } from './audio_original.js';", 'const {AUDIO_USE,usesOriginal,checkOriginal,checkedLength,failureText,multipleText,createUseSwitch,originalBlocked,stuckText,liftBlock} = globalThis.__freevideoEntryTest;');
         await import('data:text/javascript;base64,' + Buffer.from(source).toString('base64'));
         const extension = extensions.find(row => row.name === 'FreeVideo.UnifiedMedia');
         assert.ok(extension, 'the main extension must register');
diff --git a/web/audio_original.css b/web/audio_original.css
index be4b686e..accd617f 100644
--- a/web/audio_original.css
+++ b/web/audio_original.css
@@ -5,6 +5,10 @@
 .fv-audio-use button:last-child{border-radius:0 var(--fv-r-sm,8px) var(--fv-r-sm,8px) 0}
 .fv-audio-use button[aria-pressed=true]{background:var(--fv-selected);color:var(--fv-accent);border-color:var(--fv-accent);position:relative}
 .fv-audio-use button:disabled{cursor:default}
+.fv-audio-use button[data-blocked]{opacity:.6}
 .fv-audio-lock{display:inline-flex;margin-left:6px;vertical-align:-3px;color:var(--fv-muted)}
 .fv-audio-lock svg{width:13px;height:13px}
 .fv-audio-lock[hidden]{display:none}
+.fv-audio-use-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:6px 0 0;text-align:left}
+.fv-audio-use-note.fv-error{color:var(--fv-danger)}
+.fv-audio-use-note[hidden]{display:none}
diff --git a/web/audio_original.js b/web/audio_original.js
index 99ecdad1..556d55b7 100644
--- a/web/audio_original.js
+++ b/web/audio_original.js
@@ -50,13 +50,28 @@ export function failureText(result, t) {
 }
 
 // Where the engine refuses Use as is (continuing a video, a first-pass preview), the Studio
-// names that state here and the option is greyed out on every audio card until it ends.
-const blockers = new Set();
+// names that state here. The option stays clickable: a click first lifts the cause where the
+// Studio can (`release()` returns the one-line note of what it changed) and otherwise says
+// why it cannot (`text`, an [English, Chinese] pair).
+const blockers = new Map();
 export const originalBlocked = () => blockers.size > 0;
-export function blockOriginal(reason, on) {
-    const before = blockers.size > 0;
-    if (on) blockers.add(reason); else blockers.delete(reason);
-    if (before !== blockers.size > 0) window.dispatchEvent(new CustomEvent('freevideo-audio-blocked'));
+// Blocked by something a click cannot lift: the card is drawn dimmed, not disabled.
+export const originalStuck = () => [...blockers.values()].some(how => !how.release);
+export function blockOriginal(reason, on, how = {}) {
+    const before = blockers.size > 0, stuckBefore = originalStuck();
+    if (on) blockers.set(reason, how); else blockers.delete(reason);
+    if (before !== blockers.size > 0 || stuckBefore !== originalStuck()) window.dispatchEvent(new CustomEvent('freevideo-audio-blocked'));
+}
+// Why a click cannot lift the block, or '' when it can.
+export function stuckText(t) {
+    const how = [...blockers.values()].find(entry => !entry.release);
+    return how ? t(...(how.text || ['"Use as is" is not available here.', '这里不能“原样使用”。'])) : '';
+}
+// Lifts every cause that a click can lift: {ok: true, note} with what was changed, else {ok: false, text}.
+export function liftBlock(t) {
+    const notes = [];
+    for (const how of [...blockers.values()]) if (how.release) { const note = how.release(); if (note) notes.push(t(...note)); }
+    return originalBlocked() ? {ok: false, text: stuckText(t)} : {ok: true, note: notes.join(' ')};
 }
 
 export const multipleText = t => t('Choose "Use as is" for only one audio file.', '一次只能有一段音频选择“原样使用”。');
@@ -77,7 +92,10 @@ export function createUseSwitch({t, use, onPick}) {
     const apply = () => {
         for (const [name, b] of Object.entries(buttons)) {
             b.setAttribute('aria-pressed', String(name === chosen));
-            b.disabled = working || (name === AUDIO_USE.original && originalBlocked());
+            b.disabled = working;
+            const stuck = name === AUDIO_USE.original && originalStuck();
+            b.toggleAttribute('data-blocked', stuck);
+            if (stuck) b.setAttribute('aria-disabled', 'true'); else b.removeAttribute('aria-disabled');
         }
     };
     group.set = (value, busy = false) => { chosen = value; working = busy; apply(); };
diff --git a/web/freevideo.js b/web/freevideo.js
index 5491d098..ce34a9ed 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -34,7 +34,7 @@ import { uploadMedia } from './media_upload.js';
 import { swapState, requestRows, swapMissing, withPrefix } from './replace_state.js';
 import { swapMissingText } from './replace_person.js';
 import { issueButton } from './issue_button.js';
-import { AUDIO_USE, usesOriginal, checkOriginal, checkedLength, failureText, multipleText, createUseSwitch, originalBlocked } from './audio_original.js';
+import { AUDIO_USE, usesOriginal, checkOriginal, checkedLength, failureText, multipleText, createUseSwitch, originalBlocked, stuckText, liftBlock } from './audio_original.js';
 
 const languageOverride = typeof location !== 'undefined'
     ? new URLSearchParams(location.search).get('freevideo_lang') : null;
@@ -262,21 +262,40 @@ function mediaPanel(node, mount = null) {
         rows[at] = {...rest, file: source}; update(rows);
         message(text('Restored the original image. Edit it again to reapply the changes.', '已恢复原图；再次编辑可以重新应用修改。'));
     }
+    // The one-line note under an audio card's Reference | Use as is switch: what a click changed, or why it cannot.
+    let useNote = null;
+    const paintUseNote = box => { box.textContent = useNote.value; box.classList.toggle('fv-error', useNote.error); box.hidden = false; };
+    const clearUseNote = () => { useNote = null; for (const box of cards.querySelectorAll('.fv-audio-use-note')) box.hidden = true; };
+    window.addEventListener('freevideo-audio-blocked', clearUseNote);
     // Reference | Use as is: the choice is checked against the file before it is kept.
     function useSwitch(row) {
+        const say = (value, error = false) => {
+            useNote = {file: row.file, value, error};
+            const box = [...cards.querySelectorAll('.fv-audio-use-note')].find(b => b.dataset.file === row.file); // the card may have been drawn again since the click
+            if (box) { paintUseNote(box); box.scrollIntoView({block: 'nearest'}); }
+        };
         const group = createUseSwitch({t: text, use: usesOriginal(row) ? AUDIO_USE.original : AUDIO_USE.reference, onPick: async value => {
             const current = read(), at = current.findIndex(r => r.file === row.file);
             if (at < 0) return;
+            clearUseNote();
             if (value === AUDIO_USE.reference) { const {use: _use, range: _range, ...rest} = current[at]; current[at] = rest; update(current); return; }
             if (current.some((other, i) => i !== at && other.enabled !== false && usesOriginal(other))) { message(multipleText(text), true); return; }
+            // A continued video cannot be lifted from here: say why. A preview is turned off once the clip passes its check.
+            if (stuckText(text)) { say(stuckText(text), true); return; }
+            const lifting = originalBlocked();
             group.set(AUDIO_USE.original, true);
             const result = await checkOriginal(api, {...current[at], use: AUDIO_USE.original});
             const latest = read(), now = latest.findIndex(r => r.file === row.file);
             if (now < 0) return;
             if (!result.ok) { group.set(AUDIO_USE.reference); message(failureText(result, text), true); return; }
-            // A preview or a continued video turned on while the clip was checked: it stays a reference.
-            if (originalBlocked()) { group.set(AUDIO_USE.reference); return; }
+            let note = '';
+            if (lifting) {
+                const lifted = liftBlock(text);
+                if (!lifted.ok) { group.set(AUDIO_USE.reference); say(lifted.text, true); return; }
+                note = lifted.note;
+            } else if (originalBlocked()) { group.set(AUDIO_USE.reference); return; } // a preview or a continued video turned on while the clip was checked: it stays a reference
             latest[now] = {...latest[now], use: AUDIO_USE.original}; update(latest);
+            if (note) say(note);
         }});
         return group;
     }
@@ -335,6 +354,11 @@ function mediaPanel(node, mount = null) {
             if (row.source) top.append(el('span', text('Edited', '已编辑'), 'fv-edited'));
             if (kind === "audio") top.append(useSwitch(row)); else top.append(select);
             card.append(top);
+            if (kind === "audio") {
+                const useBox = el('div', '', 'fv-audio-use-note'); useBox.setAttribute('role', 'status'); useBox.dataset.file = row.file; useBox.hidden = true;
+                if (useNote?.file === row.file) paintUseNote(useBox);
+                card.append(useBox);
+            }
             const preview = el(kind === "image" ? "img" : kind); preview.className = "fv-preview";
             preview.src = viewURL(row.file);
             if (kind === "image") {
@@ -448,7 +472,7 @@ function mediaPanel(node, mount = null) {
     panel.ondragover = event => { event.preventDefault(); event.stopPropagation(); };
     panel.ondrop = event => { event.preventDefault(); event.stopPropagation(); upload(event.dataTransfer.files); };
     panel.onpaste = event => { if (event.clipboardData?.files.length) { event.preventDefault(); event.stopPropagation(); upload(event.clipboardData.files); } };
-    const dispose = () => { window.removeEventListener('freevideo-media', changed); cast.destroy(); places.destroy(); };
+    const dispose = () => { window.removeEventListener('freevideo-media', changed); window.removeEventListener('freevideo-audio-blocked', clearUseNote); cast.destroy(); places.destroy(); };
     if (mount) { mount.append(panel); render(); return dispose; }
     node.freevideoCreateMediaEditor = target => mediaPanel(node, target);
     node.addDOMWidget("freevideo_media", "freevideo_media", panel, {serialize: false, getMinHeight: () => 300, getMaxHeight: () => 520});
diff --git a/web/studio.js b/web/studio.js
index df61d749..93ff5bab 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -1146,7 +1146,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
             if (runButtonReady) updateRunButton();
         }
         previewFirst.disabled = !twoPass.checked || linked(node, 'preview') || !widget(node, 'preview');
-        blockOriginal('preview', previewFirst.checked && !previewFirst.disabled);
+        blockOriginal('preview', previewFirst.checked && !previewFirst.disabled, {release() { choosePassMode('on'); return ['Preview first was turned off for "Use as is".', '已为“原样使用”关闭“先出预览”。']; }});
         syncPassMode();
         baseSteps.disabled = baseLinked || !widget(node, 'base_steps') || Boolean(extension.source);
         refineSteps.disabled = !twoPass.checked || linked(node, 'refine_steps') || !widget(node, 'refine_steps') || Boolean(extension.source);
@@ -2172,7 +2172,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
     function syncExtension() {
         releaseExtendThumbnail(); extendMount.replaceChildren();
         const source = extension.source;
-        extendMount.hidden = !source; mediaMount.classList.toggle('fv-extend-active', Boolean(source)); blockOriginal('extend', Boolean(source));
+        extendMount.hidden = !source; mediaMount.classList.toggle('fv-extend-active', Boolean(source)); blockOriginal('extend', Boolean(source), {text: ['"Use as is" is not available while continuing a video. Remove "Continues this video" first.', '接在视频之后时不能“原样使用”，请先移除“接在这条视频后面”。']});
         if (source) runMode = 'single';
         canvasLock.hidden = !source;
         mp.disabled = width.disabled = height.disabled = Boolean(source) || dimensionsLinked;

From 98961aea0994f13389d40a7178af2d77f93213d7 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 4 Nov 2026 04:14:27 +0000
Subject: [PATCH 26/26] Release 0.4.31

---
 freevideo_engine/release_notes.json | 83 +++++++++++++++++++++--------
 1 file changed, 60 insertions(+), 23 deletions(-)

diff --git a/freevideo_engine/release_notes.json b/freevideo_engine/release_notes.json
index 705cfdcc..64627f72 100644
--- a/freevideo_engine/release_notes.json
+++ b/freevideo_engine/release_notes.json
@@ -1,37 +1,74 @@
 {
   "schema": 1,
-  "product_version": "0.4.30",
+  "product_version": "0.4.31",
   "en": {
-    "summary": "Image generation on Windows machines with little memory no longer stops while the model loads, large requests are steadier in the second pass, and the editor, the launcher and phone access now explain what stopped and what to do next.",
+    "summary": "The Edit view can now record audio against the picture, a sound clip can be separated into dialogue, music and ambience tracks, and timed lines and cuts written in a description are placed at those times in the generated video.",
     "changes": [
-      "Image generation: on Windows machines with little free memory, loading the image model no longer crashes. If loading is interrupted anyway, FreeVideo retries the request once automatically.",
-      "Generation: large requests on Windows are less likely to run out of memory in the second pass, and when they do, the retry is aimed at the memory that actually ran short instead of falling back to much slower settings. A generation also no longer stops when a memory copy is refused during sampling.",
-      "Creation panel: a note appears when other programs are using enough GPU memory or RAM to slow a generation down, and a generation that fails because of that shortage says so.",
-      "Prompt enhancement: a prompt over the 12,000-character limit now shows its current length, counting the descriptions of characters mentioned with @, before anything is sent. When the prompt or references change while a rewrite is running, a plain note says so instead of a red error. Time points later than the end of the video no longer cause an error; they are fitted within the video's length.",
-      "Editor: playback stops with a notice at a clip that cannot be played, instead of running on over a black picture. After FreeVideo restarts, interrupted exports, multi-part generations and subtitle jobs no longer show as in progress, and can be started again or continued.",
-      "Phone access: when phone access cannot be opened, the page says why and offers \"Try again\", instead of showing \"Opening...\" indefinitely.",
-      "Start-up: the launcher's failure cards now explain the cause and the next step. An access-denied error is titled \"Access denied\" and shows where access was denied; a port in use offers \"Change address\"; a refused setup step, an expired diagnostic report and a failed report export also show the next step. When Python fails to install during setup, the card shows the installer's own error message instead of only an exit code. Exporting a report can replace an existing file.",
-      "Install: while a downloaded image model file is being verified, its card says \"Checking\". On Windows, entry folders left in the shared FV folder by removed installations are cleaned up. If the setup tool has gone missing before an install step, it is downloaded again instead of the step failing.",
-      "Multi-GPU machines: requests from the Creation panel and the Agent that include images, continue a clip or are longer now run on a free card alongside other generations. A single very large task runs on its own instead of waiting in the queue indefinitely.",
-      "GPU memory: very long second passes, such as ones with large reference videos, need less GPU memory on smaller cards. When other programs take GPU memory during a run, decoding adapts instead of failing and starting over. Results are unchanged."
+      "Recording: the Edit view can now record audio against the picture. The recording is placed on a sound track, aligned with the picture.",
+      "Separate tracks: a sound clip can be split into dialogue, music and ambience tracks, each adjusted and exported on its own. Separated music can be replaced from the generation bar with \"Replace music\": new music is made at the original length and lowered where people speak.",
+      "Timed lines and cuts: write lines such as \"0:02 Jay: ...\" or \"0:05 Cut: ...\" in the description, and the generated video places dialogue and shot changes at those times. A time beyond the video length or an empty cut is flagged before generation.",
+      "Preview first: the editor's generation bar can make a preview first. A selected preview part can run its second pass with \"Run second pass\" and is replaced in place at full quality. \"Reuse settings\" also fills in the original seed.",
+      "Ripple delete: deleting a clip in the editor also closes the gap it leaves.",
+      "Recent videos and Creations fold the videos of one task into a group. Click the cover to open it.",
+      "Progress estimate: the estimated total time of a request with a long reference video is no longer far above the real time. Speed and results are unchanged.",
+      "Start-up: the launcher now opens when the bridge folder is redirected. A failed model upgrade keeps its cause in the diagnostic report and points to \"Try again\" or \"Report a problem\". The launch progress names the GPU detection, acceleration test and workflow-node connection steps, a slow full log export shows how many files have been packed, and a failed start in the terminal points to the diagnose command.",
+      "Install: on some Linux systems, setup no longer stops while building GPU acceleration.",
+      "Mac: a fault while encoding a reference video is corrected or reported within seconds instead of at the end of encoding. When a Light or Medium text-to-video generation without references or continuation is interrupted during the first pass, the automatic retry continues from the last completed step instead of starting the pass over.",
+      "Speed: on 6 GB-class cards on Windows, each sampling step of a High generation with references is faster.",
+      "Audio cards: \"Use as is\" now stays clickable when Preview first is on or a video is being continued. Choosing it turns the preview off with a one-line note, and a continuation says why it cannot be used and what to remove."
     ]
   },
   "zh": {
-    "summary": "内存较小的 Windows 机器生成图片时，不再在加载模型时中断；大画面请求的第二遍更稳定；剪辑视图、启动器和手机访问出问题时，会说明原因和下一步。",
+    "summary": "剪辑视图可以对着画面录音；一段声音可以分成人声、音乐和环境声三条轨道；在描述里按时间写的台词和切镜，生成的视频会按写定的时间安排。",
     "changes": [
-      "图像生成：可用内存较小的 Windows 机器加载图像模型时不再崩溃。加载仍意外中断时，FreeVideo 会自动重试一次。",
-      "生成：Windows 上的大画面请求在第二遍更不容易出现内存不足；出现时，重试会针对实际不足的那部分内存，不再退到慢得多的设置。采样中途内存拷贝被拒绝时，生成也不再中止。",
-      "创作面板：其他程序占用的显存或内存会使生成变慢时，面板会提示；因此类不足导致生成失败时，失败卡片同样说明这一点。",
-      "提示词增强：提示词超过 12,000 字符上限时，发送前会显示当前字数，展开的 @角色描述一并计入。改写过程中原文或素材有改动时，改为普通提示，不再显示红色错误。提示词里晚于视频结尾的时间点不再报错，会调整到视频时长以内。",
-      "剪辑视图：播放到无法播放的素材时会停下并提示，不再黑屏空走。FreeVideo 重启后，中断的导出、分段生成和字幕任务不再显示为进行中，可以重新开始或继续。",
-      "手机访问：手机连接无法打开时，网页会说明原因并提供“重试”，不再一直显示“正在打开…”。",
-      "启动：启动器的失败卡片会说明原因和下一步。拒绝访问类错误的标题为“访问被拒绝”，并写出被拒绝的位置；端口被占用时提供“更改地址”；安装步骤被拒绝、诊断报告过期和导出报告失败时，也会给出下一步。安装过程中 Python 安装失败时，失败卡片会显示安装器的报错，而不只是退出码。导出报告时可以覆盖已有文件。",
-      "安装：下载完成的图像模型文件在校验时，卡片显示“正在校验”。Windows 上，已删除的安装在共用 FV 目录里留下的入口目录会被清理。安装步骤开始前如果安装工具缺失，会重新下载，安装步骤不再因此失败。",
-      "多显卡机器：创作面板和 Agent 发出的带图、续接或较长的请求，现在可以在空闲的显卡上与其他生成同时运行。单个很大的任务改为单独运行，不再一直排队。",
-      "显存：较长的第二遍（例如参考视频很大的请求）在小显存显卡上占用的显存更少。运行中其他程序占用显存时，解码会自行调整，不再失败后重新开始。结果不变。"
+      "录音：在剪辑视图里对着画面录一段声音，录好后放到声音轨上，与画面对齐。",
+      "分离音轨：把一段声音分成人声、音乐和环境声三条轨道，每条都可单独调整和导出。分离出的音乐可在生成条点“替换配乐”，按原长度重新配乐，并在说话处压低。",
+      "按时间写台词和切镜：在描述里写“0:02 阿杰：……”或“0:05 切：……”，生成的视频会按写定的时间安排台词和镜头切换；时间超出视频长度或“切：”后面没有内容时，生成前给出提示。",
+      "先出预览：剪辑视图生成条可选“先出预览”；选中预览片段可点“继续二采”，在原位置换成完整画质。点“复用设置”时，原来的种子也一并填入。",
+      "波纹删除：在剪辑视图删除片段时，同时合上它留下的空隙。",
+      "最近作品和作品库将同一任务的多条视频折叠成一组，点封面展开。",
+      "进度估计：带较长参考视频的请求，估计的总时间不再远高于实际用时。速度和结果不变。",
+      "启动：启动器在桥接目录被重定向时也能打开。模型升级失败时，诊断报告保留失败原因，并提示可点“重试”或“提交问题”。启动进度会写出检测显卡、测试加速和连接工作流节点这几步；导出完整日志较慢时显示已打包的文件数；在终端里启动失败时，会提示运行诊断命令。",
+      "安装：部分 Linux 系统上，安装不再停在构建 GPU 加速这一步。",
+      "Mac：参考视频编码出错时，几秒内即修正或报告，不再等到编码结束。轻量或标准档、不带参考、不续接的文生视频在第一遍被中断后，自动重试会从最后完成的步骤继续，不再从头开始这一遍。",
+      "速度：Windows 上的 6 GB 级显卡，带参考的精细档生成每一步采样更快。",
+      "音频卡：“先出预览”开启或接着生成时，“原样使用”不再变灰。选择它会关闭预览并用一行说明；接着生成时说明原因和需要移除的内容。"
     ]
   },
   "history": [
+    {
+      "product_version": "0.4.30",
+      "en": {
+        "summary": "Image generation on Windows machines with little memory no longer stops while the model loads, large requests are steadier in the second pass, and the editor, the launcher and phone access now explain what stopped and what to do next.",
+        "changes": [
+          "Image generation: on Windows machines with little free memory, loading the image model no longer crashes. If loading is interrupted anyway, FreeVideo retries the request once automatically.",
+          "Generation: large requests on Windows are less likely to run out of memory in the second pass, and when they do, the retry is aimed at the memory that actually ran short instead of falling back to much slower settings. A generation also no longer stops when a memory copy is refused during sampling.",
+          "Creation panel: a note appears when other programs are using enough GPU memory or RAM to slow a generation down, and a generation that fails because of that shortage says so.",
+          "Prompt enhancement: a prompt over the 12,000-character limit now shows its current length, counting the descriptions of characters mentioned with @, before anything is sent. When the prompt or references change while a rewrite is running, a plain note says so instead of a red error. Time points later than the end of the video no longer cause an error; they are fitted within the video's length.",
+          "Editor: playback stops with a notice at a clip that cannot be played, instead of running on over a black picture. After FreeVideo restarts, interrupted exports, multi-part generations and subtitle jobs no longer show as in progress, and can be started again or continued.",
+          "Phone access: when phone access cannot be opened, the page says why and offers \"Try again\", instead of showing \"Opening...\" indefinitely.",
+          "Start-up: the launcher's failure cards now explain the cause and the next step. An access-denied error is titled \"Access denied\" and shows where access was denied; a port in use offers \"Change address\"; a refused setup step, an expired diagnostic report and a failed report export also show the next step. When Python fails to install during setup, the card shows the installer's own error message instead of only an exit code. Exporting a report can replace an existing file.",
+          "Install: while a downloaded image model file is being verified, its card says \"Checking\". On Windows, entry folders left in the shared FV folder by removed installations are cleaned up. If the setup tool has gone missing before an install step, it is downloaded again instead of the step failing.",
+          "Multi-GPU machines: requests from the Creation panel and the Agent that include images, continue a clip or are longer now run on a free card alongside other generations. A single very large task runs on its own instead of waiting in the queue indefinitely.",
+          "GPU memory: very long second passes, such as ones with large reference videos, need less GPU memory on smaller cards. When other programs take GPU memory during a run, decoding adapts instead of failing and starting over. Results are unchanged."
+        ]
+      },
+      "zh": {
+        "summary": "内存较小的 Windows 机器生成图片时，不再在加载模型时中断；大画面请求的第二遍更稳定；剪辑视图、启动器和手机访问出问题时，会说明原因和下一步。",
+        "changes": [
+          "图像生成：可用内存较小的 Windows 机器加载图像模型时不再崩溃。加载仍意外中断时，FreeVideo 会自动重试一次。",
+          "生成：Windows 上的大画面请求在第二遍更不容易出现内存不足；出现时，重试会针对实际不足的那部分内存，不再退到慢得多的设置。采样中途内存拷贝被拒绝时，生成也不再中止。",
+          "创作面板：其他程序占用的显存或内存会使生成变慢时，面板会提示；因此类不足导致生成失败时，失败卡片同样说明这一点。",
+          "提示词增强：提示词超过 12,000 字符上限时，发送前会显示当前字数，展开的 @角色描述一并计入。改写过程中原文或素材有改动时，改为普通提示，不再显示红色错误。提示词里晚于视频结尾的时间点不再报错，会调整到视频时长以内。",
+          "剪辑视图：播放到无法播放的素材时会停下并提示，不再黑屏空走。FreeVideo 重启后，中断的导出、分段生成和字幕任务不再显示为进行中，可以重新开始或继续。",
+          "手机访问：手机连接无法打开时，网页会说明原因并提供“重试”，不再一直显示“正在打开…”。",
+          "启动：启动器的失败卡片会说明原因和下一步。拒绝访问类错误的标题为“访问被拒绝”，并写出被拒绝的位置；端口被占用时提供“更改地址”；安装步骤被拒绝、诊断报告过期和导出报告失败时，也会给出下一步。安装过程中 Python 安装失败时，失败卡片会显示安装器的报错，而不只是退出码。导出报告时可以覆盖已有文件。",
+          "安装：下载完成的图像模型文件在校验时，卡片显示“正在校验”。Windows 上，已删除的安装在共用 FV 目录里留下的入口目录会被清理。安装步骤开始前如果安装工具缺失，会重新下载，安装步骤不再因此失败。",
+          "多显卡机器：创作面板和 Agent 发出的带图、续接或较长的请求，现在可以在空闲的显卡上与其他生成同时运行。单个很大的任务改为单独运行，不再一直排队。",
+          "显存：较长的第二遍（例如参考视频很大的请求）在小显存显卡上占用的显存更少。运行中其他程序占用显存时，解码会自行调整，不再失败后重新开始。结果不变。"
+        ]
+      }
+    },
     {
       "product_version": "0.4.29",
       "en": {