---
name: ai-vid-stock
description: "Manage AI video stock materials on TrueNAS — add, search, list, and remove assets across all 12 stock categories plus supplementary folders."
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [ai-video, stock-materials, truenas, smb, ltx, comfyui]
---

# AI Video Stock Material Manager

Manage stock materials for the LTX video pipeline stored on TrueNAS at `10.0.0.117`.

## Storage Location

| Setting | Value |
|---------|-------|
| Server | 10.0.0.117 (TrueNAS) |
| Share | proxmoxBackup (read-write, guest access) |
| Root path | `ai_vid_stock_material/` |
| Access | `smbclient -N //10.0.0.117/proxmoxBackup` |

## Authoritative Inventory

**The README.md on the share is the canonical inventory.** Always consult it first for the current folder list, contents, file counts, and sizes. Download it with:

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material; get README.md /tmp/ai_vid_stock_readme.md'
```

The README tracks: folder structure, file counts, sizes, reorg history, and stock-search acquisition logs. When adding/removing files, update the README.

## Directory Structure (current as of 2026-07-29)

### 12 Canonical Stock Categories

| # | Folder | Purpose |
|---|--------|---------|
| 01 | `character_sheets/` | Character reference packs — turnarounds, expression sheets, pose variety |
| 02 | `environments_start_frames/` | Location/scene stills for I2V start frames |
| 03 | `end_frames/` | Target/last-frame stills for FLF I2V generation |
| 04 | `props_objects/` | Isolated prop/object reference images |
| 05 | `style_frames/` | Mood/style reference stills (color grade, lighting) |
| 06 | `control_pose_references/` | Pose/depth/canny control images |
| 07 | `motion_reference_clips/` | Short reference video clips for motion-transfer |
| 08 | `storyboard_previs_frames/` | Rough sequential previs frames |
| 09 | `texture_material_plates/` | Texture/material reference plates |
| 10 | `audio_stock/` | TTS clips, ambient sounds, music |
| 11 | `lora_weights_generation_params/` | Trained LoRA weights + generation params |
| 12 | `vehicles_creatures_effects/` | Vehicle/creature/VFX element reference images |

### Supplementary Infra Folders

| Folder | Purpose |
|--------|---------|
| `outputs/` | Rendered LTX video outputs (final concats + per-run subfolders) |
| `workflows/` | ComfyUI workflow JSONs |
| `docs/` | Pipeline planning docs, research notes, story prompt docs |
| `scripts/` | Generation scripts, automation |
| `my_images/` | Operator-supplied source images (input material, not finished stock) |
| `backup_files/` | ComfyUI model/module cold storage (preserves /models/ path) |
| `lora/` | LoRA weight files (.safetensors) for active use — raw weights only |

## Commands

All commands use `smbclient -N //10.0.0.117/proxmoxBackup`. The share root is `ai_vid_stock_material/`.

### List all folders

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material; ls'
```

### List contents of a specific folder

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material; ls <folder>/*'
```

### Search across all stock categories by filename pattern

```bash
for dir in character_sheets environments_start_frames end_frames props_objects style_frames control_pose_references motion_reference_clips storyboard_previs_frames texture_material_plates audio_stock lora_weights_generation_params vehicles_creatures_effects lora; do
  echo "=== $dir ==="
  smbclient -N //10.0.0.117/proxmoxBackup -c "cd ai_vid_stock_material; ls $dir/*" 2>/dev/null | grep -i "<pattern>"
done
```

### Add a file (upload)

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material/<folder>; put <local_path> <remote_filename>'
```

### Add from remote server (e.g., .202 ComfyUI)

```bash
# 1. Pull from remote
scp n8n@10.0.0.202:<remote_path> /tmp/<filename>

# 2. Upload to TrueNAS
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material/<folder>; put /tmp/<filename> <filename>'
```

### Remove a file

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material/<folder>; rm <filename>'
```

### Download a file

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material/<folder>; get <filename> <local_path>'
```

### Download entire folder

```bash
mkdir -p /tmp/stock_dl/<folder>
cd /tmp/stock_dl/<folder>
smbclient -N //10.0.0.117/proxmoxBackup -c "cd ai_vid_stock_material/<folder>; prompt OFF; mget *"
```

### Create a new folder

```bash
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material; mkdir <new_folder>'
```

### Update README after changes

```bash
# Download
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material; get README.md /tmp/ai_vid_stock_readme.md'
# Edit /tmp/ai_vid_stock_readme.md
# Upload
smbclient -N //10.0.0.117/proxmoxBackup -c 'cd ai_vid_stock_material; put /tmp/ai_vid_stock_readme.md README.md'
```

## Category Guidelines

| Folder | What goes here | File types |
|--------|---------------|------------|
| `character_sheets/` | Character reference packs — turnarounds, expression sheets, pose variety, hero portraits | .png, .jpg |
| `environments_start_frames/` | Location/scene stills used as I2V start frames | .png, .jpg, .jpeg |
| `end_frames/` | Target/last-frame stills for FLF I2V generation | .png, .jpg |
| `props_objects/` | Isolated prop/object reference images for compositing | .png, .jpg |
| `style_frames/` | Mood/style reference stills (color grade, lighting language) | .png, .jpg |
| `control_pose_references/` | Pose/depth/canny control images for guided generation | .png, .jpg |
| `motion_reference_clips/` | Short reference video clips for motion-transfer / IC-LoRA Control | .mp4, .mov, .webm |
| `storyboard_previs_frames/` | Rough sequential previs frames for planning shot flow | .png, .jpg |
| `texture_material_plates/` | Texture/material reference plates (concrete, metal, fabric, etc.) | .png, .jpg |
| `audio_stock/` | TTS clips, ambient sounds, music for video | .mp3, .wav |
| `lora_weights_generation_params/` | Trained LoRA .safetensors + saved generation parameters (prompts/seeds/workflow configs) | .safetensors, .json, .txt |
| `vehicles_creatures_effects/` | Vehicle/creature/VFX element reference images | .png, .jpg |
| `lora/` | Raw LoRA weight files (.safetensors) for active ComfyUI use — drop here, load from here | .safetensors |
| `outputs/` | Rendered LTX video outputs | .mp4 |
| `workflows/` | ComfyUI workflow JSONs exported from UI | .json |
| `docs/` | Pipeline planning docs, research notes, story prompt docs | .md, .txt |
| `scripts/` | Generation scripts, prompt templates, automation | .py, .sh, .json, .txt |
| `my_images/` | Operator-supplied source images — input material, not finished stock | .png, .jpg |
| `backup_files/` | ComfyUI model/module cold storage — preserves full /models/ path | .safetensors, .pt, .ckpt, .gguf |

## Pitfalls

- **SMB path separators are backslashes** — use `cd ai_vid_stock_material\\<folder>` in smbclient, not forward slashes. Forward slashes work in the `-c` flag string but backslashes are needed for nested paths in interactive mode.
- **No mount available** — the cifs kernel module is not present on the Hermes host. Use smbclient for all operations. Do not attempt `mount.cifs`.
- **smbclient `mget`/`mput` need `prompt OFF`** — otherwise it prompts for every file.
- **Spaces in filenames** — quote them in smbclient commands.
- **Keep README.md updated** — it's the inventory of record. After any add/remove, update it.
- **TrueNAS guest access** — no credentials needed. If auth errors appear, the share config may have changed.
- **Large files** — smbclient `put`/`get` works for files up to several GB. For bulk transfers, consider using the TrueNAS web UI at `http://10.0.0.117`.
- **`lora/` vs `lora_weights_generation_params/`** — `lora/` is for raw .safetensors weights ready to load. `lora_weights_generation_params/` is for weights WITH their training configs and generation parameters. Don't mix them.

## LTX Pipeline Wiring Bug (2026-07-21)

**Symptom:** Subject duplication in LTX Director renders — a frozen duplicate of the start frame appears alongside the generated motion. All outputs are 249 frames instead of 240.

**Root cause:** Node 132 (LTXDirectorGuide refiner) takes its `latent` input from the uncropped stage-1 output (`["34", 0]`) instead of the cropped output (`["55", 2]`). The guide frames from stage 1 leak through as actual video.

**Fix:** Point `132.inputs.latent` at `["55", 2]` instead of `["34", 0]`. Verify output is exactly 240 frames.

**Reference:** `/home/n8n/workspace/general/ltx-pipeline-state.md` — full render history and diagnosis.