Character Cartridges (.joypack v1.0): spec, packer, loader node, and WREN - the first portable video-character file (verified: same face + rhotic General American voice in an unseen scene, zero training)

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 demo_one_room_q8.mp4 filter=lfs diff=lfs merge=lfs -text
+joypacks/WREN.joypack filter=lfs diff=lfs merge=lfs -text

JOYPACK_SPEC.md

@@ -0,0 +1,94 @@
+# .joypack — portable video-character cartridge (spec v1.0)
+
+One file = one character: face, voice, canon description, and optionally the
+LoRAs and environments that define them. Drop it into a JoyEcho workflow and
+render new scenes with that exact character — same face, same voice — with
+zero training. Designed to extend the roleplay ecosystem's Character Card
+V3/CHARX lineage into photoreal joint audio-video generation.
+
+## Container
+
+A `.joypack` is a ZIP archive (store or deflate) with this layout:
+
+```
+manifest.json                REQUIRED  spec + inventory (see below)
+persona/card.json            optional  CharacterCardV3-compatible JSON (chat interop)
+voice/anchor.(mp4|wav)       REQUIRED  4s+ clip of the character speaking.
+                                       Seeds the JoyEcho memory bank before
+                                       shot 1 - the voice continues instead of
+                                       being re-rolled. mp4 preferred (pairs
+                                       audio with a moving reference face).
+refs/*.png|jpg               REQUIRED  1-8 MSR identity reference stills,
+                                       front-lit face clearly visible.
+prompts/dna.txt              REQUIRED  the canonical DNA sentence(s): the
+                                       verbatim identity text to carry in every
+                                       shot prompt, plus voice scaffold line
+                                       (timbre + accent binding).
+loras/zimage/*.safetensors   optional  face LoRA for first-frame/still work
+loras/ltx/*.safetensors      optional  LTX-2.3 LoRA(s) (ID-LoRA, style)
+environment/*.png|jpg        optional  canonical location stills
+environment/rooms.txt        optional  verbatim room description(s) - the
+                                       location-lock prose, one per paragraph
+```
+
+## manifest.json
+
+```json
+{
+  "joypack": "1.0",
+  "name": "MARA",
+  "speaker_tag": "mara",
+  "display_name": "Detective Mara",
+  "authors": ["you"],
+  "license": "CC-BY-4.0",
+  "notes": "freeform",
+  "voice": {"file": "voice/anchor.mp4", "accent_line": "speaking in a casual American accent"},
+  "refs": ["refs/mara_01.png", "refs/mara_02.png"],
+  "dna": "prompts/dna.txt",
+  "loras": {
+    "zimage": [{"file": "loras/zimage/mara_z.safetensors", "trigger": "mara_z", "strength": 0.7}],
+    "ltx":    [{"file": "loras/ltx/mara_id.safetensors", "strength": 1.0}]
+  },
+  "environment": {"stills": ["environment/apartment_01.png"], "rooms": "environment/rooms.txt"},
+  "render_law": {"video_fps": 24},
+  "sha256": {"voice/anchor.mp4": "..."}
+}
+```
+
+Only `joypack`, `name`, `speaker_tag`, `voice`, `refs`, and `dna` are required.
+Unknown keys MUST be ignored (forward compatibility). `render_law` records
+generation constraints the character was authored under - loaders should warn
+when the live workflow violates them (the fps/accent law above all).
+
+## Loader behavior (reference implementation: JoyEcho_CartridgeLoader)
+
+Loading MATERIALIZES the cartridge into the host's existing conventions -
+the render path itself needs no changes:
+
+1. Unpack to a cache dir keyed by content hash.
+2. Copy `voice/anchor.*` to `input/joyecho_voices/<speaker_tag>/` (folder
+   auto-casting picks it up; every script whose speaker tag matches is voiced
+   by the anchor).
+3. Copy `refs/*` to the workflow's refs root under `<speaker_tag>/` (RefPicker
+   finds them by character scan).
+4. Copy LoRAs to `models/loras/joypack/<name>/` and report their names for the
+   LoRA stack.
+5. Output the DNA text, accent line, room text, and trigger words as node
+   outputs for prompt assembly.
+6. Verify sha256 entries when present; refuse a cartridge whose manifest is
+   missing required keys.
+
+Removal = delete the materialized folders; a cartridge never modifies the
+host beyond those drop-in locations.
+
+## Security
+
+A cartridge is DATA. Loaders MUST NOT execute anything from the archive, MUST
+reject path traversal (entries containing `..` or absolute paths), and should
+treat persona/card.json purely as chat-client payload. LoRA files are weights;
+standard safetensors-only policy applies (no pickle formats).
+
+## Versioning
+
+`joypack: "1.0"` this document. Planned 1.1: serialized memory-bank state
+(`bank/state.joybank`) for scene-warm characters; multi-character packs.

__init__.py

@@ -159,4 +159,16 @@ try:
 except Exception as e:
     print(f"[Rebels JE] joyecho_autofinish failed to load: {e!r}", flush=True)
 
-__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]
+try:
+    from .joyecho_cartridge import (
+        NODE_CLASS_MAPPINGS as _CG_CM,
+        NODE_DISPLAY_NAME_MAPPINGS as _CG_DM,
+    )
+    NODE_CLASS_MAPPINGS.update(_CG_CM)
+    NODE_DISPLAY_NAME_MAPPINGS.update(_CG_DM)
+except Exception as _e:
+    print(f"[JoyAI-Echo] cartridge loader unavailable: {_e}")
+
+WEB_DIRECTORY = "./web/js"
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", "WEB_DIRECTORY"]

joyecho_cartridge.py

@@ -0,0 +1,104 @@
+"""JoyEcho_CartridgeLoader - load a .joypack character cartridge.
+
+Materializes the cartridge into the host's existing conventions (voice anchor
+into input/joyecho_voices/<tag>/, reference stills into the refs root, LoRAs
+into models/loras/joypack/<name>/) and outputs the character's texts for
+prompt assembly. The render path needs no changes - after loading, any script
+whose speaker tag matches is voiced and identified as the cartridge character.
+
+See JOYPACK_SPEC.md for the format.
+"""
+import json
+import os
+
+try:
+    import folder_paths
+except Exception:
+    folder_paths = None
+
+from .joypack import materialize, read_manifest, JoypackError
+
+
+def _packs_dir():
+    if folder_paths:
+        base = folder_paths.get_input_directory()
+    else:
+        base = os.path.join(os.getcwd(), "input")
+    d = os.path.join(base, "joypacks")
+    os.makedirs(d, exist_ok=True)
+    return d
+
+
+class JoyEcho_CartridgeLoader:
+    @classmethod
+    def INPUT_TYPES(cls):
+        packs = ["(none)"]
+        try:
+            packs += sorted(f for f in os.listdir(_packs_dir())
+                            if f.lower().endswith(".joypack"))
+        except Exception:
+            pass
+        return {
+            "required": {
+                "cartridge": (packs, {
+                    "tooltip": "A .joypack from input/joypacks/. Loading installs "
+                               "the character's voice anchor, reference stills and "
+                               "LoRAs into this workflow's normal folders - any "
+                               "script whose speaker tag matches renders as this "
+                               "character. See JOYPACK_SPEC.md."}),
+                "refs_root": ("STRING", {"default": "joyecho_refs", "tooltip":
+                              "Where reference stills install (RefPicker's root). "
+                              "Absolute path or relative to the input folder."}),
+            },
+        }
+
+    RETURN_TYPES = ("STRING", "STRING", "STRING", "STRING", "STRING")
+    RETURN_NAMES = ("speaker_tag", "dna_text", "accent_line", "rooms_text", "report")
+    FUNCTION = "load"
+    CATEGORY = "JoyAI-Echo"
+
+    def load(self, cartridge, refs_root="joyecho_refs"):
+        if cartridge == "(none)":
+            return ("", "", "", "", "no cartridge selected")
+        pack_path = os.path.join(_packs_dir(), cartridge)
+
+        in_dir = (folder_paths.get_input_directory() if folder_paths
+                  else os.path.join(os.getcwd(), "input"))
+        voices_dir = os.path.join(in_dir, "joyecho_voices")
+        refs_dir = (refs_root if os.path.isabs(refs_root)
+                    else os.path.join(in_dir, refs_root))
+        if folder_paths:
+            loras_dir = os.path.join(folder_paths.models_dir, "loras", "joypack")
+        else:
+            loras_dir = os.path.join(os.getcwd(), "models", "loras", "joypack")
+        cache_dir = os.path.join(in_dir, "joypacks", "_cache")
+
+        try:
+            res = materialize(pack_path, voices_dir, refs_dir, loras_dir, cache_dir)
+        except (JoypackError, OSError) as e:
+            raise ValueError(f"joypack load failed: {e}")
+
+        law = res.get("render_law", {})
+        law_note = ""
+        if law.get("video_fps"):
+            law_note = (f" | render law: video_fps={law['video_fps']} "
+                        f"(authored under the 24fps accent law)" if law["video_fps"] == 24
+                        else f" | render law: video_fps={law['video_fps']}")
+        loras_note = ""
+        if res["ltx_loras"]:
+            loras_note = " | LTX loras: " + ", ".join(
+                f"{os.path.basename(l['path'])}@{l['strength']}" for l in res["ltx_loras"])
+        report = (f"loaded '{res['name']}' as speaker '{res['speaker_tag']}' - "
+                  f"voice anchor + {sum(1 for p in res['installed_paths'] if refs_dir in p)} "
+                  f"ref(s) installed{loras_note}{law_note}")
+        print(f"[JoyEcho] Cartridge: {report}", flush=True)
+
+        dna = res["dna"]
+        if res.get("triggers"):
+            dna = dna  # triggers are for Z-Image prompts; reported, not injected
+        return (res["speaker_tag"], dna, res.get("accent_line", ""),
+                res.get("rooms", ""), report)
+
+
+NODE_CLASS_MAPPINGS = {"JoyEcho_CartridgeLoader": JoyEcho_CartridgeLoader}
+NODE_DISPLAY_NAME_MAPPINGS = {"JoyEcho_CartridgeLoader": "JoyEcho Cartridge Loader (.joypack)"}

joypack.py

@@ -0,0 +1,208 @@
+"""joypack - portable video-character cartridges (.joypack), spec v1.0.
+
+Library + CLI. See JOYPACK_SPEC.md for the format. A .joypack is a plain zip;
+this module packs one from a source folder and safely unpacks/materializes one
+into the JoyEcho host conventions (joyecho_voices/<tag>/, refs root, loras).
+
+CLI:
+    python joypack.py pack   <source_dir> <out.joypack>
+    python joypack.py inspect <file.joypack>
+
+Security: archives are DATA. No execution, no path traversal (rejected), no
+pickle weight formats (safetensors only for loras/).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import sys
+import zipfile
+
+SPEC_VERSION = "1.0"
+REQUIRED_KEYS = ("joypack", "name", "speaker_tag", "voice", "refs", "dna")
+VOICE_EXTS = (".mp4", ".wav")
+REF_EXTS = (".png", ".jpg", ".jpeg", ".webp")
+
+
+class JoypackError(ValueError):
+    pass
+
+
+def _sha256(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _safe_name(entry_name):
+    """Reject traversal and absolute paths; return normalized relative path."""
+    n = entry_name.replace("\\", "/")
+    if n.startswith("/") or ".." in n.split("/") or (len(n) > 1 and n[1] == ":"):
+        raise JoypackError(f"unsafe path in archive: {entry_name!r}")
+    return n
+
+
+def pack(source_dir, out_path):
+    """Build a .joypack from a folder laid out per the spec.
+
+    If the folder has no manifest.json, a minimal one is synthesized from the
+    layout (name = folder name, speaker_tag = lowercased name).
+    """
+    source_dir = os.path.abspath(source_dir)
+    man_path = os.path.join(source_dir, "manifest.json")
+    if os.path.isfile(man_path):
+        manifest = json.load(open(man_path, encoding="utf-8"))
+    else:
+        name = os.path.basename(source_dir.rstrip("\\/"))
+        manifest = {"joypack": SPEC_VERSION, "name": name,
+                    "speaker_tag": name.lower()}
+
+    # discover required components if unlisted
+    def _find(sub, exts):
+        d = os.path.join(source_dir, sub)
+        if not os.path.isdir(d):
+            return []
+        return sorted(f"{sub}/{f}" for f in os.listdir(d)
+                      if f.lower().endswith(exts))
+
+    if "voice" not in manifest or not manifest["voice"].get("file"):
+        vs = _find("voice", VOICE_EXTS)
+        if not vs:
+            raise JoypackError("no voice anchor found (voice/anchor.mp4|wav)")
+        manifest.setdefault("voice", {})["file"] = vs[0]
+    if not manifest.get("refs"):
+        manifest["refs"] = _find("refs", REF_EXTS)
+        if not manifest["refs"]:
+            raise JoypackError("no reference stills found (refs/*.png)")
+    if not manifest.get("dna"):
+        p = "prompts/dna.txt"
+        if not os.path.isfile(os.path.join(source_dir, p)):
+            raise JoypackError("no DNA text found (prompts/dna.txt)")
+        manifest["dna"] = p
+    manifest.setdefault("render_law", {"video_fps": 24})
+
+    # collect every real file under the spec dirs + the manifest
+    files = []
+    for root, _, names in os.walk(source_dir):
+        for fn in names:
+            full = os.path.join(root, fn)
+            rel = os.path.relpath(full, source_dir).replace("\\", "/")
+            if rel == "manifest.json":
+                continue
+            if rel.startswith("loras/") and not fn.lower().endswith(".safetensors"):
+                raise JoypackError(f"loras/ may only contain .safetensors: {rel}")
+            files.append(rel)
+
+    manifest["sha256"] = {manifest["voice"]["file"]:
+                          _sha256(os.path.join(source_dir, manifest["voice"]["file"]))}
+    for k in REQUIRED_KEYS:
+        if k not in manifest:
+            raise JoypackError(f"manifest missing required key: {k}")
+
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("manifest.json", json.dumps(manifest, indent=1))
+        for rel in files:
+            z.write(os.path.join(source_dir, rel), rel)
+    return out_path, manifest
+
+
+def read_manifest(pack_path):
+    with zipfile.ZipFile(pack_path) as z:
+        try:
+            manifest = json.loads(z.read("manifest.json").decode("utf-8"))
+        except KeyError:
+            raise JoypackError("not a joypack: manifest.json missing")
+    for k in REQUIRED_KEYS:
+        if k not in manifest:
+            raise JoypackError(f"manifest missing required key: {k}")
+    return manifest
+
+
+def materialize(pack_path, voices_dir, refs_dir, loras_dir, cache_dir):
+    """Unpack + install a cartridge into host conventions.
+
+    Returns a dict: {name, speaker_tag, dna, accent_line, rooms, triggers,
+                     ltx_loras, zimage_loras, installed_paths}
+    """
+    manifest = read_manifest(pack_path)
+    tag = manifest["speaker_tag"]
+    name = manifest["name"]
+    out = {"name": name, "speaker_tag": tag, "installed_paths": []}
+
+    with zipfile.ZipFile(pack_path) as z:
+        names = {_safe_name(n) for n in z.namelist()}
+
+        def _extract(member, dst_dir, dst_name=None):
+            member = _safe_name(member)
+            if member not in names:
+                raise JoypackError(f"manifest references missing file: {member}")
+            os.makedirs(dst_dir, exist_ok=True)
+            dst = os.path.join(dst_dir, dst_name or os.path.basename(member))
+            with z.open(member) as src, open(dst, "wb") as f:
+                shutil.copyfileobj(src, f)
+            out["installed_paths"].append(dst)
+            return dst
+
+        # voice anchor -> joyecho_voices/<tag>/
+        vfile = manifest["voice"]["file"]
+        want = manifest.get("sha256", {}).get(vfile)
+        vdst = _extract(vfile, os.path.join(voices_dir, tag))
+        if want and _sha256(vdst) != want:
+            os.remove(vdst)
+            raise JoypackError("voice anchor failed sha256 verification")
+
+        # refs -> <refs_root>/<NAME>/
+        for r in manifest["refs"]:
+            _extract(r, os.path.join(refs_dir, name))
+
+        # loras -> models/loras/joypack/<name>/
+        out["ltx_loras"], out["zimage_loras"] = [], []
+        loras = manifest.get("loras", {})
+        for fam, key in (("ltx", "ltx_loras"), ("zimage", "zimage_loras")):
+            for entry in loras.get(fam, []) or []:
+                dst = _extract(entry["file"], os.path.join(loras_dir, name))
+                out[key].append({"path": dst,
+                                 "strength": float(entry.get("strength", 1.0)),
+                                 "trigger": entry.get("trigger", "")})
+
+        # texts
+        out["dna"] = z.read(_safe_name(manifest["dna"])).decode("utf-8").strip()
+        out["accent_line"] = manifest.get("voice", {}).get("accent_line", "")
+        rooms = manifest.get("environment", {}).get("rooms")
+        out["rooms"] = (z.read(_safe_name(rooms)).decode("utf-8").strip()
+                        if rooms and _safe_name(rooms) in names else "")
+        env_stills = manifest.get("environment", {}).get("stills", []) or []
+        for s in env_stills:
+            _extract(s, os.path.join(cache_dir, name, "environment"))
+
+    out["render_law"] = manifest.get("render_law", {})
+    out["triggers"] = [e.get("trigger", "") for e in
+                       (manifest.get("loras", {}).get("zimage", []) or []) if e.get("trigger")]
+    return out
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(__doc__)
+        return 1
+    cmd = sys.argv[1]
+    if cmd == "pack":
+        out, man = pack(sys.argv[2], sys.argv[3])
+        print(f"packed {man['name']} -> {out}")
+        print(f"  speaker_tag={man['speaker_tag']} refs={len(man['refs'])} "
+              f"voice={man['voice']['file']}")
+    elif cmd == "inspect":
+        man = read_manifest(sys.argv[2])
+        print(json.dumps(man, indent=1))
+    else:
+        print(__doc__)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

joypacks/WREN.joypack

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:664ec73cbd0d52088765ae87f584407993c4ad308aea539f8e0c2f99b1ed5652
+size 2682926

nodes.py

@@ -1224,7 +1224,7 @@ class JoyEcho_Generate:
                 "model": ("JOYECHO_MODEL",),
                 "conditioning": ("JOYECHO_COND",),
                 "seed": ("INT", {"default": 12345, "min": 0, "max": 2**31 - 1}),
-                "num_frames": ("INT", {"default": 241, "min": 9, "max": 481, "step": 8,
+                "num_frames": ("INT", {"default": 241, "min": 9, "max": 1441, "step": 8,
                                        "tooltip": "Must be 1 + 8*k (e.g. 121, 241, 361)"}),
                 # Rebels local patch: portrait resolutions. Height was capped at
                 # 1088 while width allowed 1920, which silently forbade portrait
@@ -1380,6 +1380,19 @@ class JoyEcho_Generate:
                                "it) - use heights whose /32 is EVEN (768, not 736) or it "
                                "smears one edge.",
                 }),
+                "temporal_upscale": (["off", "2x (48 fps master)"], {
+                    "default": "off",
+                    "tooltip": "LTX temporal latent upsampler (x2) on each shot's OWN latents "
+                               "after sampling: per-shot files and the master come out at "
+                               "double fps (24 -> ~48) with the audio untouched - same "
+                               "duration, twice the motion samples, no optical-flow ghosting. "
+                               "The render itself stays at video_fps 24, so the accent/sync "
+                               "law is unaffected; the in-canvas preview also stays at base "
+                               "fps (only the saved files double). v1 limitation: requires "
+                               "hires_factor 1.0 (skipped with a warning otherwise). Keep OFF "
+                               "for found-footage looks - interpolated camcorder reads as "
+                               "soap opera.",
+                }),
             },
         }
 
@@ -1449,6 +1462,7 @@ class JoyEcho_Generate:
         resident_blocks: int = 0,
         hires_factor: float = 1.0,
         hires_denoise: str = "subtle (1 step)",
+        temporal_upscale: str = "off",
     ):
         from ltx_distillation.inference.bidirectional_pipeline import BidirectionalAVInferencePipeline
         from ltx_distillation.inference.memory_bidirectional_pipeline import BidirectionalMemoryAVInferencePipeline
@@ -1617,6 +1631,12 @@ class JoyEcho_Generate:
         _hires_audio_lats = []
         _hires_video_lats = []  # spatial hires mode only (~10MB/shot on CPU)
         _hires_spatial = str(hires_denoise).lower().startswith("spatial")
+        _temporal_on = str(temporal_upscale).lower().startswith("2x")
+        if _temporal_on and hires_factor > 1.0:
+            print("[JoyEcho] temporal_upscale requires hires_factor 1.0 in this "
+                  "version - the hires passes re-save shots at base fps and would "
+                  "undo it. Temporal upscale SKIPPED.", flush=True)
+            _temporal_on = False
 
         num_shots = len(conditioning)
         offloader = None
@@ -2050,6 +2070,23 @@ class JoyEcho_Generate:
             if device.type == "cuda":
                 torch.cuda.synchronize()
 
+            # Temporal x2: second decode from the shot's OWN latents through the
+            # LTX temporal upsampler while the decoder is still on GPU. Only the
+            # SAVED shot files (and thus the worker-built master) get the doubled
+            # fps; the bank, refs and in-graph frames stay base-fps native.
+            _tu_uint8 = None
+            if _temporal_on:
+                try:
+                    _tu_uint8 = self._temporal_upsample_decode(
+                        video_vae, video_latent, _decode_tiling_config, device)
+                    print(f"[JoyEcho] temporal x2: shot {shot_idx+1} "
+                          f"{video_uint8.shape[0]}f -> {_tu_uint8.shape[0]}f "
+                          f"(saved at {video_fps * 2} fps).", flush=True)
+                except Exception as _tu_e:
+                    print(f"[JoyEcho] temporal x2 FAILED on shot {shot_idx+1}: "
+                          f"{_tu_e} - saving base-fps shot instead.", flush=True)
+                    _tu_uint8 = None
+
             # Move VAE back to CPU
             _move(video_vae.decoder, "cpu")
             _move(audio_vae.decoder, "cpu")
@@ -2097,6 +2134,8 @@ class JoyEcho_Generate:
                 _trim = max(_trim, _t1)
             if _trim > 0 and video_uint8.shape[0] > _trim + 16:
                 video_uint8 = video_uint8[_trim:]
+                if _tu_uint8 is not None:
+                    _tu_uint8 = _tu_uint8[2 * _trim:]  # same cut in doubled frames
                 if audio_waveform is not None:
                     _cut = int(round(_trim / float(video_fps) * audio_sample_rate))
                     if audio_waveform.shape[-1] > _cut:
@@ -2131,10 +2170,19 @@ class JoyEcho_Generate:
 
             # Save per-shot video immediately for real-time preview (now trimmed,
             # so it matches the final output frame-for-frame).
-            self._save_shot_video(
-                video_uint8, audio_waveform, shot_idx,
-                video_fps, audio_sample_rate, output_prefix
-            )
+            if _tu_uint8 is not None:
+                # doubled-fps shot file: the AutoFinish worker probes r_frame_rate
+                # per shot, so the master assembles at the doubled rate untouched
+                self._save_shot_video(
+                    _tu_uint8, audio_waveform, shot_idx,
+                    video_fps * 2, audio_sample_rate, output_prefix
+                )
+                del _tu_uint8
+            else:
+                self._save_shot_video(
+                    video_uint8, audio_waveform, shot_idx,
+                    video_fps, audio_sample_rate, output_prefix
+                )
 
             del video_latent, audio_latent, audio_memory_latent, video_uint8, audio_waveform
             _empty_cache()
@@ -2653,6 +2701,71 @@ class JoyEcho_Generate:
             _empty_cache()
         print(f"[JoyEcho] Hires refine pass done in {_time.time()-_t0:.0f}s.", flush=True)
 
+    def _temporal_upsample_decode(self, video_vae, video_latent, tiling_config, device):
+        """Decode a shot's video latents through the LTX temporal x2 upsampler.
+
+        Mirrors the hires-spatial pass: pipeline latents [1,F,C,h,w] ->
+        un-normalize -> reflect-pad T (the upsampler family corrupts sequence
+        ends; pads absorb it) -> upsample -> crop pad -> re-normalize -> tiled
+        decode. Deterministic, video-only - the audio lane is never touched.
+        Returns uint8 frames with F_out ~= 2*F-1. Decoder must already be on
+        `device` (call inside Phase B).
+        """
+        import json as _json
+        import folder_paths
+        import comfy.utils as _cutils
+        from comfy.ldm.lightricks.latent_upsampler import LatentUpsampler
+        from ltx_core.model.video_vae import TemporalTilingConfig, TilingConfig
+        from ltx_distillation.utils import decode_benchmark_sample
+
+        # The doubled sequence (~2x frames) MUST decode temporally tiled no
+        # matter what the shot's own tiling resolved to - an untiled 449-frame
+        # decode is exactly the uncatchable native cuDNN abort the tiled-decode
+        # work fixed (killed the whole process on first try, 2026-07-30).
+        tiling_config = TilingConfig(
+            spatial_config=None,
+            temporal_config=TemporalTilingConfig(tile_size_in_frames=64,
+                                                 tile_overlap_in_frames=24))
+
+        _dt = torch.bfloat16
+        cls = type(self)
+        if getattr(cls, "_tu_model", None) is None:
+            path = folder_paths.get_full_path_or_raise(
+                "latent_upscale_models",
+                "ltx-2.3-temporal-upscaler-x2-1.0.safetensors")
+            sd, metadata = _cutils.load_torch_file(
+                path, safe_load=True, return_metadata=True)
+            m = LatentUpsampler.from_config(
+                _json.loads(metadata["config"])).to(dtype=_dt)
+            m.load_state_dict(sd)
+            m.eval()
+            cls._tu_model = m
+            del sd
+        up_model = cls._tu_model.to(device)
+
+        stats = video_vae.decoder.per_channel_statistics  # on device with decoder
+        raw = video_latent.permute(0, 2, 1, 3, 4)          # [1,C,F,h,w]
+        raw = stats.un_normalize(raw.to(device=device, dtype=torch.float32))
+        f_in = raw.shape[2]
+        p = min(8, f_in - 1)
+        if p > 0:
+            raw = torch.cat([raw[:, :, 1:p + 1].flip(2), raw,
+                             raw[:, :, -(p + 1):-1].flip(2)], dim=2)
+        with torch.no_grad():
+            up = up_model(raw.to(dtype=_dt))
+        _scale = up.shape[2] / raw.shape[2]
+        del raw
+        if p > 0:
+            _po = int(round(p * _scale))
+            up = up[:, :, _po:up.shape[2] - _po]
+        up = stats.normalize(up.to(torch.float32)).to(_dt)
+        up = up.permute(0, 2, 1, 3, 4).contiguous()        # [1,F2,C,h,w]
+        u8, _ = decode_benchmark_sample(video_vae, None, up.to(device), None,
+                                        video_tiling_config=tiling_config)
+        del up
+        up_model.to("cpu")
+        return u8
+
     @staticmethod
     def _save_shot_video(video_uint8, audio_waveform, shot_idx, fps, audio_sr, prefix):
         """Save a single shot as mp4 immediately after generation."""
@@ -2766,7 +2879,7 @@ class JoyEcho_SingleShotGenerate:
                     "tooltip": "Single shot prompt text",
                 }),
                 "seed": ("INT", {"default": 12345, "min": 0, "max": 2**31 - 1}),
-                "num_frames": ("INT", {"default": 241, "min": 9, "max": 481, "step": 8,
+                "num_frames": ("INT", {"default": 241, "min": 9, "max": 1441, "step": 8,
                                        "tooltip": "Must be 1 + 8*k (e.g. 121, 241, 361)"}),
                 # Rebels local patch: portrait resolutions. Height was capped at
                 # 1088 while width allowed 1920, which silently forbade portrait

web/js/joyecho_widget_persistence.js

@@ -0,0 +1,57 @@
+// JoyEcho widget persistence - values survive node-layout changes.
+//
+// ComfyUI serializes widgets_values as a POSITIONAL array. Whenever a JoyEcho
+// node gains/loses/reorders a widget between saves, every saved value shifts
+// into the wrong slot or silently reverts to defaults - the "my settings reset
+// after every update" complaint, and the reason the Generate node ships a
+// scramble-guard error at all.
+//
+// Fix: on serialize, ALSO store {widgetName: value} in node.properties (a
+// dict - layout-immune). On configure, after the stock positional restore,
+// re-apply values BY NAME. Combo values that no longer exist in the current
+// option list are skipped so a renamed dropdown option falls back to its
+// default instead of erroring.
+//
+// First save under this extension writes the map; from then on, layout
+// changes can never revert your settings again.
+
+import { app } from "../../scripts/app.js";
+
+const PREFIX = "JoyEcho_";
+const PROP = "je_widget_values";
+
+app.registerExtension({
+    name: "joyecho.widgetPersistence",
+    beforeRegisterNodeDef(nodeType, nodeData) {
+        if (!nodeData?.name?.startsWith(PREFIX)) return;
+
+        const origSerialize = nodeType.prototype.onSerialize;
+        nodeType.prototype.onSerialize = function (o) {
+            origSerialize?.apply(this, arguments);
+            if (!this.widgets?.length) return;
+            const map = {};
+            for (const w of this.widgets) {
+                if (w.name !== undefined && w.value !== undefined) {
+                    map[w.name] = w.value;
+                }
+            }
+            o.properties = o.properties || {};
+            o.properties[PROP] = map;
+        };
+
+        const origConfigure = nodeType.prototype.onConfigure;
+        nodeType.prototype.onConfigure = function (o) {
+            origConfigure?.apply(this, arguments);
+            const saved = o?.properties?.[PROP];
+            if (!saved || !this.widgets?.length) return;
+            for (const w of this.widgets) {
+                if (!(w.name in saved)) continue;
+                const v = saved[w.name];
+                const opts = w.options?.values;
+                if (Array.isArray(opts) && !opts.includes(v)) continue; // renamed combo option
+                w.value = v;
+                w.callback?.(v);
+            }
+        };
+    },
+});