Bring upstream/main up to date with origin/main

- Add IC-LoRA support with depth (MiDaS DPT-Hybrid) and pose (DW Pose) conditioning pipelines
- Embed IC-LoRA UI in Gen Space, Playground, and Video Editor
- Add conditioning cache for IC-LoRA pipeline outputs
- Refactor model download APIs to explicit model type selection with spec-based sizing and session-tracked progress
- Consolidate ModelFileId and ModelFileType into single ModelFileType
- Unify IC-LoRA model download flow into main download system (remove separate ic_lora_model_downloader)
- Add secure models directory change support with admin token guard
- Harden project assets path IPC against renderer abuse
- Ensure backend error responses never return empty error messages
- Unify output video sizing to match input video aspect ratio

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ofirgluzman

AGENTS.md

@@ -24,7 +24,7 @@ LTX Desktop is an Electron app for AI video generation using LTX models. Three-l
 | `pnpm build:mac` / `pnpm build:win` | Full platform builds |
 | `pnpm setup:dev:mac` / `pnpm setup:dev:win` | One-time dev environment setup |
 
-Run a single backend test: `cd backend && uv run pytest tests/test_generation.py -v --tb=short`
+Run a single backend test file via pnpm: `pnpm backend:test -- tests/test_ic_lora.py`
 
 ## CI Checks
 
@@ -36,7 +36,7 @@ PRs must pass: `pnpm typecheck` + `pnpm backend:test` + frontend Vite build.
 - **State management**: React contexts only (`ProjectContext`, `AppSettingsContext`, `KeyboardShortcutsContext`) — no Redux/Zustand
 - **Routing**: View-based via `ProjectContext` with views: `home`, `project`, `playground`
 - **IPC bridge**: All Electron communication through `window.electronAPI` (defined in `electron/preload.ts`)
-- **Backend calls**: Frontend calls `http://localhost:8000` directly
+- **Backend calls**: Always use `backendFetch` from `frontend/lib/backend.ts` for app backend HTTP requests (it attaches auth/session details). Do not call `fetch` directly for backend endpoints.
 - **Styling**: Tailwind with custom semantic color tokens via CSS variables; utilities from `class-variance-authority` + `clsx` + `tailwind-merge`
 - **No frontend tests** currently exist
 

NOTICES.md

@@ -22,6 +22,21 @@ used by LTX Desktop.
   License: Apache License 2.0
   https://huggingface.co/Tongyi-MAI/Z-Image-Turbo
 
+- **DPT-Hybrid (MiDaS 3.0)**
+  Copyright (c) Intel Corporation.
+  License: Apache License 2.0
+  https://huggingface.co/Intel/dpt-hybrid-midas
+
+- **DW Pose TorchScript (BatchSize5)**
+  Copyright (c) DWPose contributors.
+  License: Apache License 2.0
+  https://huggingface.co/hr16/DWPose-TorchScript-BatchSize5
+
+- **YOLOX Person Detector (TorchScript)**
+  Copyright (c) YOLOX contributors.
+  License: Apache License 2.0
+  https://huggingface.co/hr16/yolox-onnx
+
 ---
 
 ## Python Dependencies

backend/_routes/_admin_guard.py

@@ -0,0 +1,17 @@
+"""Admin token guard for privileged settings mutations."""
+
+from __future__ import annotations
+
+import hmac
+
+from fastapi import Request
+
+from _routes._errors import HTTPError
+
+
+def guard_admin_permission(request: Request) -> None:
+    """Raise 403 if the request lacks a valid admin token."""
+    admin_token: str = getattr(request.app.state, "admin_token", "")
+    provided = request.headers.get("X-Admin-Token", "")
+    if not admin_token or not provided or not hmac.compare_digest(provided, admin_token):
+        raise HTTPError(403, "Admin token required")

backend/_routes/ic_lora.py

@@ -5,33 +5,17 @@
 from fastapi import APIRouter, Depends
 
 from api_types import (
-    IcLoraDownloadRequest,
-    IcLoraDownloadResponse,
     IcLoraExtractRequest,
     IcLoraExtractResponse,
     IcLoraGenerateRequest,
     IcLoraGenerateResponse,
-    IcLoraListResponse,
 )
 from state import get_state_service
 from app_handler import AppHandler
 
 router = APIRouter(prefix="/api/ic-lora", tags=["ic-lora"])
 
 
-@router.get("/list-models", response_model=IcLoraListResponse)
-def route_ic_lora_list_models(handler: AppHandler = Depends(get_state_service)) -> IcLoraListResponse:
-    return handler.ic_lora.list_models()
-
-
-@router.post("/download-model", response_model=IcLoraDownloadResponse)
-def route_ic_lora_download(
-    req: IcLoraDownloadRequest,
-    handler: AppHandler = Depends(get_state_service),
-) -> IcLoraDownloadResponse:
-    return handler.ic_lora.download_model(req)
-
-
 @router.post("/extract-conditioning", response_model=IcLoraExtractResponse)
 def route_ic_lora_extract(
     req: IcLoraExtractRequest,

backend/_routes/models.py

@@ -4,14 +4,15 @@
 
 import logging
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Query
 
 from api_types import (
     DownloadProgressResponse,
     ModelDownloadRequest,
     ModelDownloadStartResponse,
     ModelInfo,
     ModelsStatusResponse,
+    RequiredModelsResponse,
     TextEncoderDownloadResponse,
 )
 from _routes._errors import HTTPError
@@ -34,8 +35,24 @@ def route_models_status(handler: AppHandler = Depends(get_state_service)) -> Mod
 
 
 @router.get("/models/download/progress", response_model=DownloadProgressResponse)
-def route_download_progress(handler: AppHandler = Depends(get_state_service)) -> DownloadProgressResponse:
-    return handler.downloads.get_download_progress()
+def route_download_progress(
+    sessionId: str = Query(...),
+    handler: AppHandler = Depends(get_state_service),
+) -> DownloadProgressResponse:
+    try:
+        return handler.downloads.get_download_progress(sessionId)
+    except ValueError as exc:
+        raise HTTPError(404, str(exc))
+
+
+@router.get("/models/required-models", response_model=RequiredModelsResponse)
+def route_required_models(
+    skipTextEncoder: bool = Query(default=False),
+    handler: AppHandler = Depends(get_state_service),
+) -> RequiredModelsResponse:
+    return RequiredModelsResponse(
+        modelTypes=handler.models.get_required_model_types(skip_text_encoder=skipTextEncoder),
+    )
 
 
 @router.post("/models/download", response_model=ModelDownloadStartResponse)
@@ -46,16 +63,12 @@ def route_model_download(
     if handler.downloads.is_download_running():
         raise HTTPError(409, "Download already in progress")
 
-    settings = handler.settings.get_settings_snapshot()
-    skip_text_encoder = req.skipTextEncoder
-    if settings.ltx_api_key and not settings.use_local_text_encoder:
-        skip_text_encoder = True
-
-    if handler.downloads.start_model_download(skip_text_encoder=skip_text_encoder):
+    session_id = handler.downloads.start_model_download(model_types=req.modelTypes)
+    if session_id:
         return ModelDownloadStartResponse(
             status="started",
             message="Model download started",
-            skippingTextEncoder=skip_text_encoder,
+            sessionId=session_id,
         )
 
     raise HTTPError(400, "Failed to start download")
@@ -70,7 +83,8 @@ def route_text_encoder_download(handler: AppHandler = Depends(get_state_service)
     if files["text_encoder"] is not None:
         return TextEncoderDownloadResponse(status="already_downloaded", message="Text encoder already downloaded")
 
-    if handler.downloads.start_text_encoder_download():
-        return TextEncoderDownloadResponse(status="started", message="Text encoder download started")
+    session_id = handler.downloads.start_text_encoder_download()
+    if session_id:
+        return TextEncoderDownloadResponse(status="started", message="Text encoder download started", sessionId=session_id)
 
     raise HTTPError(400, "Failed to start download")

backend/_routes/settings.py

@@ -4,8 +4,9 @@
 
 import logging
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Request
 
+from _routes._admin_guard import guard_admin_permission
 from state.app_settings import SettingsResponse, UpdateSettingsRequest, to_settings_response
 from api_types import StatusResponse
 from state import get_state_service
@@ -24,8 +25,13 @@ def route_get_settings(handler: AppHandler = Depends(get_state_service)) -> Sett
 @router.post("/settings", response_model=StatusResponse)
 def route_post_settings(
     req: UpdateSettingsRequest,
+    request: Request,
     handler: AppHandler = Depends(get_state_service),
 ) -> StatusResponse:
+    patch_data = req.model_dump(exclude_unset=True)
+    if "models_dir" in patch_data or "modelsDir" in patch_data:
+        guard_admin_permission(request)
+
     _, _after, changed_paths = handler.settings.update_settings(req)
     changed_roots = {path.split(".", 1)[0] for path in changed_paths}
 

backend/api_types.py

@@ -8,6 +8,17 @@
 from pydantic import BaseModel, Field, StringConstraints
 
 NonEmptyPrompt = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+ModelFileType = Literal[
+    "checkpoint",
+    "upsampler",
+    "distilled_lora",
+    "ic_lora",
+    "depth_processor",
+    "person_detector",
+    "pose_processor",
+    "text_encoder",
+    "zit",
+]
 
 
 class ImageConditioningInput(NamedTuple):
@@ -35,19 +46,6 @@ class GenerationState(TypedDict):
     total_steps: int
 
 
-class ModelDownloadState(TypedDict):
-    status: str  # "idle" | "downloading" | "complete" | "error"
-    current_file: str
-    current_file_progress: int
-    total_progress: int
-    downloaded_bytes: int
-    total_bytes: int
-    files_completed: int
-    total_files: int
-    error: str | None
-    speed_mbps: int
-
-
 JsonObject: TypeAlias = dict[str, object]
 VideoCameraMotion = Literal[
     "none",
@@ -117,6 +115,7 @@ class ModelInfo(BaseModel):
 
 
 class ModelFileStatus(BaseModel):
+    id: ModelFileType
     name: str
     description: str
     downloaded: bool
@@ -149,27 +148,15 @@ class ModelsStatusResponse(BaseModel):
 
 class DownloadProgressResponse(BaseModel):
     status: str
-    currentFile: str
-    currentFileProgress: int
-    totalProgress: int
-    downloadedBytes: int
-    totalBytes: int
-    filesCompleted: int
-    totalFiles: int
+    current_downloading_file: ModelFileType | None
+    current_file_progress: int
+    total_progress: int
+    total_downloaded_bytes: int
+    expected_total_bytes: int
+    completed_files: set[ModelFileType]
+    all_files: set[ModelFileType]
     error: str | None
-    speedMbps: int
-
-
-class IcLoraModel(BaseModel):
-    name: str
-    path: str
-    conditioning_type: str
-    reference_downscale_factor: int
-
-
-class IcLoraListResponse(BaseModel):
-    models: list[IcLoraModel]
-    directory: str
+    speed_mbps: int
 
 
 class SuggestGapPromptResponse(BaseModel):
@@ -201,17 +188,10 @@ class RetakeResponse(BaseModel):
 class IcLoraExtractResponse(BaseModel):
     conditioning: str
     original: str
-    conditioning_type: str
+    conditioning_type: Literal["canny", "depth", "pose"]
     frame_time: float
 
 
-class IcLoraDownloadResponse(BaseModel):
-    status: str
-    path: str | None = None
-    already_existed: bool | None = None
-    already_exists: bool | None = None
-
-
 class IcLoraGenerateResponse(BaseModel):
     status: str
     video_path: str | None = None
@@ -220,12 +200,13 @@ class IcLoraGenerateResponse(BaseModel):
 class ModelDownloadStartResponse(BaseModel):
     status: str
     message: str | None = None
-    skippingTextEncoder: bool | None = None
+    sessionId: str | None = None
 
 
 class TextEncoderDownloadResponse(BaseModel):
     status: str
     message: str | None = None
+    sessionId: str | None = None
 
 
 class StatusResponse(BaseModel):
@@ -264,8 +245,16 @@ class GenerateImageRequest(BaseModel):
     numImages: int = 1
 
 
+def _default_model_types() -> set[ModelFileType]:
+    return set()
+
+
 class ModelDownloadRequest(BaseModel):
-    skipTextEncoder: bool = False
+    modelTypes: set[ModelFileType] = Field(default_factory=_default_model_types)
+
+
+class RequiredModelsResponse(BaseModel):
+    modelTypes: list[ModelFileType]
 
 
 class SuggestGapPromptRequest(BaseModel):
@@ -286,13 +275,9 @@ class RetakeRequest(BaseModel):
     mode: str = "replace_audio_and_video"
 
 
-class IcLoraDownloadRequest(BaseModel):
-    model: str
-
-
 class IcLoraExtractRequest(BaseModel):
     video_path: str
-    conditioning_type: str = "canny"
+    conditioning_type: Literal["canny", "depth", "pose"] = "canny"
     frame_time: float = 0
 
 
@@ -308,15 +293,9 @@ def _default_ic_lora_images() -> list[IcLoraImageInput]:
 
 class IcLoraGenerateRequest(BaseModel):
     video_path: str
-    lora_path: str
-    conditioning_type: str = "canny"
+    conditioning_type: Literal["canny", "depth", "pose"]
     prompt: NonEmptyPrompt
     conditioning_strength: float = 1.0
-    seed: int = 42
-    height: int = 512
-    width: int = 768
-    num_frames: int = 121
-    frame_rate: float = 24
     num_inference_steps: int = 30
     cfg_guidance_scale: float = 1.0
     negative_prompt: str = ""

backend/app_factory.py

@@ -41,11 +41,13 @@ def create_app(
     allowed_origins: list[str] | None = None,
     title: str = "LTX-2 Video Generation Server",
     auth_token: str = "",
+    admin_token: str = "",
 ) -> FastAPI:
     """Create a configured FastAPI app bound to the provided handler."""
     init_state_service(handler)
 
     app = FastAPI(title=title)
+    app.state.admin_token = admin_token  # type: ignore[attr-defined]
     app.add_middleware(
         CORSMiddleware,
         allow_origins=allowed_origins or DEFAULT_ALLOWED_ORIGINS,
@@ -84,20 +86,22 @@ def _token_matches(candidate: str) -> bool:
                 pass
         return JSONResponse(status_code=401, content={"error": "Unauthorized"})
 
+    _FALLBACK = "An unexpected error occurred"
+
     async def _route_http_error_handler(request: Request, exc: Exception) -> JSONResponse:
         if isinstance(exc, HTTPError):
             log_http_error(request, exc)
-            return JSONResponse(status_code=exc.status_code, content={"error": exc.detail})
-        return JSONResponse(status_code=500, content={"error": str(exc)})
+            return JSONResponse(status_code=exc.status_code, content={"error": exc.detail or _FALLBACK})
+        return JSONResponse(status_code=500, content={"error": str(exc) or _FALLBACK})
 
     async def _validation_error_handler(request: Request, exc: Exception) -> JSONResponse:
         if isinstance(exc, RequestValidationError):
-            return JSONResponse(status_code=422, content={"error": str(exc)})
-        return JSONResponse(status_code=422, content={"error": str(exc)})
+            return JSONResponse(status_code=422, content={"error": str(exc) or _FALLBACK})
+        return JSONResponse(status_code=422, content={"error": str(exc) or _FALLBACK})
 
     async def _route_generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
         log_unhandled_exception(request, exc)
-        return JSONResponse(status_code=500, content={"error": str(exc)})
+        return JSONResponse(status_code=500, content={"error": str(exc) or _FALLBACK})
 
     app.add_exception_handler(RequestValidationError, _validation_error_handler)
     app.add_exception_handler(HTTPError, _route_http_error_handler)