### LoadAudioUpload Node Usage Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/05-audio-nodes.md

Demonstrates how to instantiate the LoadAudioUpload node and load audio files. Shows examples for loading the entire file and a specific portion.

```python
loader = LoadAudioUpload()

# Load uploaded audio
audio, dur = loader.load_audio(
    audio="background_music.mp3",
    start_time=0,
    duration=60
)

# Load portion of uploaded audio
audio, dur = loader.load_audio(
    audio="narration.wav",
    start_time=5.5,
    duration=30
)
```

--------------------------------

### Basic Video Viewing Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Demonstrates a simple GET request to the /vhs/viewvideo endpoint to serve a video file.

```http
GET /vhs/viewvideo?file=/path/to/video.mp4&format=video
```

--------------------------------

### FFmpeg Command Construction Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

A simplified example demonstrating how FFmpeg commands are constructed for video processing, including input, time/frame manipulation, scaling, encoding, and output format.

```bash
ffmpeg -i input.mp4 \
  -ss 5.5 \
  -r 8 \
  -vf scale=512:512 \
  -frames:v 100 \
  -c:v libvpx-vp9 \
  -deadline realtime \
  -f webm -
```

--------------------------------

### Image Sequence Folder Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Shows how to serve an image sequence from a folder by setting 'format=folder' and sampling every other frame.

```http
GET /vhs/viewvideo?file=/path/to/frames&format=folder&select_every_nth=2
```

--------------------------------

### Scaled Preview Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Demonstrates how to request a video preview at a specific resolution using the 'force_size' parameter.

```http
GET /vhs/viewvideo?file=/path/to/video.mp4&force_size=512x512
```

--------------------------------

### Load Audio with Seek Offset via /vhs/viewaudio

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

This GET request allows serving an audio file starting from a specified time offset. The 'start_time' parameter defines the seek point in seconds.

```http
GET /vhs/viewaudio?file=/path/to/audio.mp3&start_time=30.5
```

--------------------------------

### Selected Frame Range Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Illustrates requesting a specific segment of a video by setting 'start_time' and 'frame_load_cap'.

```http
GET /vhs/viewvideo?file=/path/to/video.mp4&start_time=10&frame_load_cap=50
```

--------------------------------

### Resampled Video Example (8 fps)

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Shows how to request a video with a specific output frame rate using the 'force_rate' parameter.

```http
GET /vhs/viewvideo?file=/path/to/video.mp4&force_rate=8
```

--------------------------------

### Combine Video and Audio Node Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/05-audio-nodes.md

Demonstrates how to load video and audio using respective nodes and then combine them into a single output file with specified parameters like frame rate and format.

```python
# Load video
images, frame_count, _, video_info = load_video_node(...)  # frame_count=48, 24fps = 2 seconds

# Load audio
audio, audio_dur = load_audio_node(...)  # audio_dur=2.0 seconds

# Combine
from videohelpersuite.nodes import VideoCombine
result = VideoCombine.combine_video(
    images=images,
    audio=audio,       # AUDIO dict with waveform and sample_rate
    frame_rate=24,
    filename_prefix="with_sound",
    format="video/h264-mp4"
)
```

--------------------------------

### LoadAudio Node Usage

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/05-audio-nodes.md

Demonstrates how to use the LoadAudio node to load audio files or URLs. Shows examples for loading the entire file, a specific segment, and from a URL.

```python
loader = LoadAudio()

# Load entire audio file
audio, dur = loader.load_audio(
    audio_file="/path/to/music.mp3"
)
# audio['waveform'].shape: (1, 2, 44100 * duration)
# dur: full file duration in seconds

# Load 5-second segment starting at 30 seconds
audio, dur = loader.load_audio(
    audio_file="/path/to/music.mp3",
    seek_seconds=30,
    duration=5
)
# dur: 5.0 (or less if file ends before 35 seconds)

# Load from URL
audio, dur = loader.load_audio(
    audio_file="https://example.com/audio.mp3",
    seek_seconds=0,
    duration=30
)
```

--------------------------------

### Configure AV1 WebM Video Format

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/README.md

Example JSON configuration for the Video Combine node to encode video using the AV1 codec with WebM container. This setup uses the SVT-AV1 encoder for speed and specifies pixel format and CRF for quality control. It also includes audio encoding settings and environment variables for logging.

```json
{
    "main_pass":
    [
        "-n", "-c:v", "libsvtav1",
        "-pix_fmt", "yuv420p10le",
        "-crf", ["crf","INT", {"default": 23, "min": 0, "max": 100, "step": 1}]
    ],
    "audio_pass": ["-c:a", "libopus"],
     "extension": "webm",
     "environment": {"SVT_LOG": "1"}
}
```

--------------------------------

### Example Usage of Lazy Audio Loading

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Demonstrates how to create a lazy audio object and access its properties. The audio data is loaded only upon the first access to a key like 'sample_rate'.

```python
lazy_audio = lazy_get_audio("/path/to/music.mp3", start_time=30)
# Audio not loaded yet

sample_rate = lazy_audio['sample_rate']  # Loads now
waveform = lazy_audio['waveform']        # Already loaded
```

--------------------------------

### LoadVideoPath Usage Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/03-load-video-nodes.md

Demonstrates how to use the LoadVideoPath node to load videos from an absolute file path and a remote URL. It shows setting parameters like force_rate, custom_width, custom_height, and frame_load_cap.

```python
loader = LoadVideoPath()

# Load from absolute path
images, count, audio, info = loader.load_video(
    video="/home/user/videos/source.mp4",
    force_rate=24,
    custom_width=1280,
    custom_height=720
)

# Load from URL (auto-downloads)
images, count, audio, info = loader.load_video(
    video="https://example.com/video.mp4",
    frame_load_cap=30
)
```

--------------------------------

### Create a dummy IMAGE tensor

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/11-types-and-formats.md

Example of creating a random torch.Tensor representing an IMAGE with shape (batch, height, width, channels).

```python
images = torch.randn(16, 512, 512, 3)  # 16 frames, 512×512, RGB
```

--------------------------------

### LoadImagesFromDirectoryUpload Node Usage

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/07-image-loading-nodes.md

Demonstrates how to use the LoadImagesFromDirectoryUpload node to load images from a specified directory. Includes examples for loading all images, loading in batches, and sampling every nth image.

```python
loader = LoadImagesFromDirectoryUpload()

# Load all images from a subdirectory
images, masks, count = loader.load_images(
    directory="my_sequence"  # ComfyUI/input/my_sequence/
)
# images.shape: (N, H, W, 3)
# masks.shape: (N, H, W)
# count: N

# Load images in batches
images_batch1, masks1, count1 = loader.load_images(
    directory="my_sequence",
    image_load_cap=16,      # Load 16 images
    skip_first_images=0
)

images_batch2, masks2, count2 = loader.load_images(
    directory="my_sequence",
    image_load_cap=16,      # Load next 16
    skip_first_images=16
)

# Sample every 2nd image
images_sparse, masks_sparse, count = loader.load_images(
    directory="my_sequence",
    select_every_nth=2      # Every other image
)
```

--------------------------------

### Python Return Value Format Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/README.md

Demonstrates the standard format for return values in Python functions, indicating a tuple of outputs corresponding to declared return types.

```python
return (output1, output2, ...)

```

--------------------------------

### Load Full Audio via /vhs/viewaudio

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Use this GET request to serve an entire audio file. Ensure the 'file' parameter points to the correct audio file path.

```http
GET /vhs/viewaudio?file=/path/to/audio.mp3
```

--------------------------------

### Load Video with Frame Rate and Size Adjustment

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/03-load-video-nodes.md

This example demonstrates loading a video file, resampling it to a specific frame rate, resizing it to custom dimensions, and limiting the number of frames loaded. It shows how to use parameters like `force_rate`, `custom_width`, `custom_height`, and `frame_load_cap`.

```python
loader = LoadVideoUpload()
images, frame_count, audio, video_info = loader.load_video(
    video="my_animation.mp4",
    force_rate=8,           # Resample to 8 fps
    custom_width=512,       # Resize to 512px width
    custom_height=512,      # Aspect ratio maintained
    frame_load_cap=16,      # Load only first 16 frames
    skip_first_frames=0,    # Start from frame 0
    select_every_nth=1      # Include all frames
)
# images.shape: (16, 512, 512, 3)
# frame_count: 16
```

--------------------------------

### VideoInfo Node Usage Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/06-video-metadata-nodes.md

Demonstrates how to load a video with transformations and then use the VideoInfo node to extract and print both source and loaded video metadata. This is useful for analyzing the effects of loading parameters on video properties.

```python
images, frame_count, audio, video_info = load_video_node(
    video="source.mp4",
    force_rate=8,
    custom_width=512,
    custom_height=512,
    frame_load_cap=16
)

# Extract all metadata
video_node = VideoInfo()
(source_fps, source_frames, source_dur, source_w, source_h,
 loaded_fps, loaded_frames, loaded_dur, loaded_w, loaded_h) = video_node.get_video_info(video_info)

print(f"Source: {source_fps} fps, {source_frames} frames, {source_w}x{source_h}")
# Source: 30 fps, 300 frames, 1920x1080

print(f"Loaded: {loaded_fps} fps, {loaded_frames} frames, {loaded_w}x{loaded_h}")
# Loaded: 8 fps, 16 frames, 512x512
```

--------------------------------

### Unbatch Node Usage Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/04-image-latent-nodes.md

Demonstrates how to use the unbatch node to merge two separate batches of video frames into a single batch. Assumes batch1 and batch2 are loaded from different sources.

```python
# Multiple batch inputs from different sources
batch1 = load_video_node1()  # Returns 8 frames
batch2 = load_video_node2()  # Returns 8 frames

merged = unbatch([batch1, batch2])  # Returns 16 frames
```

--------------------------------

### Get ComfyUI Directories

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Accesses the input, output, and temporary directories configured in ComfyUI. These are essential for managing files processed by the videohelper suite.

```python
import folder_paths

input_dir = folder_paths.get_input_directory()      # Input files
output_dir = folder_paths.get_output_directory()    # Saved outputs
temp_dir = folder_paths.get_temp_directory()        # Temporary files
```

--------------------------------

### ffmpeg_suitability()

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Scores an FFmpeg binary based on its codec support and copyright year. This is useful for automatically selecting the most suitable FFmpeg executable from multiple installations.

```APIDOC
## ffmpeg_suitability()

### Description
Scores an FFmpeg binary for feature completeness (codec support).

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to the FFmpeg binary.

### Returns
Integer score (higher = more suitable).

### Use Case
Auto-select best FFmpeg from multiple installations.

### Scoring Details
| Codec/Feature | Score |
|---------------|-------|
| libvpx (VP8) | 20 |
| h.264 | 10 |
| h.265 (HEVC) | 3 |
| SVT-AV1 | 5 |
| libopus | 1 |
| Copyright year 2025 | +25 |
| Copyright year 2020 | +20 |
```

--------------------------------

### Python Method Signature Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/README.md

Illustrates a typical Python method signature, including required and optional parameters, and variable keyword arguments. Shows type hints and return type annotation.

```python
def method_name(
    self,
    param1: Type1,           # Required parameter
    param2: Type2 = default, # Optional parameter
    **kwargs                 # Additional format-specific parameters
) -> (RETURN_TYPE, ...)

```

--------------------------------

### URL Format for /vhs/viewvideo Endpoint

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Illustrates the basic GET request format for the /vhs/viewvideo endpoint, including its alias.

```http
GET /vhs/viewvideo?param1=value1&param2=value2
GET /viewvideo?param1=value1&param2=value2    # Alias
```

--------------------------------

### VAEDecodeBatched Usage Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/09-vae-batch-nodes.md

Demonstrates how to use the VAEDecodeBatched node to decode latent representations into images. Ensure VAE model and latents are properly loaded.

```python
vae = load_vae_model()  # VAE decoder
latents = {
    'samples': torch.randn(256, 4, 64, 64)  # 256 latent frames
}

decoder = VAEDecodeBatched()
images = decoder.decode(vae=vae, samples=latents)
# images.shape: (256, 512, 512, 3)
```

--------------------------------

### Create MultiInput Instances

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Instantiate MultiInput to define specific type constraints for node parameters. For example, 'imageOrLatent' allows 'IMAGE' or 'LATENT' inputs.

```python
imageOrLatent = MultiInput("IMAGE", ["IMAGE", "LATENT"])
floatOrInt = MultiInput("FLOAT", ["FLOAT", "INT"])
```

--------------------------------

### Split Images Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/04-image-latent-nodes.md

Splits a batch of images into two parts at a specified index. The first part contains items from the beginning up to the split index, and the second part contains the rest. This is useful for dividing data for further processing.

```python
images_A, count_A, images_B, count_B = split_images(
    images=images,  # (32, 512, 512, 3)
    split_index=16
)
# images_A.shape: (16, 512, 512, 3), count_A: 16
# images_B.shape: (16, 512, 512, 3), count_B: 16
```

--------------------------------

### FFmpeg Command for Audio Extraction and Seeking

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

This bash command demonstrates how FFmpeg is used to extract audio from an input file, apply a start time offset, and output it as raw f32le PCM data. It is a precursor to wrapping the audio in WAV format for streaming.

```bash
ffmpeg -i input.mp3 \
  -ss 5.5 \
  -f f32le - # Then wrapped in WAV format
```

--------------------------------

### Use imageio-ffmpeg for FFmpeg

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Set this flag to exclusively use the FFmpeg build provided by the imageio_ffmpeg Python package. This ensures consistent FFmpeg behavior across different platforms but requires the package to be installed.

```bash
export VHS_USE_IMAGEIO_FFMPEG=1
```

--------------------------------

### Merge Images Node Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/04-image-latent-nodes.md

Combines two image batches, resizing the second batch to match the dimensions of the first using bilinear scaling. Useful for concatenating image sequences of different resolutions.

```python
images_A = torch.randn(8, 512, 512, 3)  # 8 images, 512x512
images_B = torch.randn(8, 768, 768, 3)  # 8 images, 768x768

merged, count = merge_images(
    images_A=images_A,
    images_B=images_B,
    merge_strategy="match A",
    scale_method="bilinear"
)
# merged.shape: (16, 512, 512, 3)
# count: 16
```

--------------------------------

### Image to Latent Encoding Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/11-types-and-formats.md

Shows the transformation of an image tensor shape to a latent tensor shape after VAE encoding, highlighting the reduction in spatial dimensions and channels.

```python
# Original image
images: Tensor(N, 512, 512, 3)

# After VAE encoding (downscale_ratio=8)
latents: dict{
    'samples': Tensor(N, 4, 64, 64)  # 512/8 = 64
}
```

--------------------------------

### AV1 Video Format JSON Configuration

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/11-types-and-formats.md

Example JSON structure for defining AV1 video encoding parameters using FFmpeg arguments, pixel format, and quality settings.

```json
{
    "main_pass": [
        "-n",
        "-c:v", "libsvtav1",
        "-pix_fmt", "yuv420p10le",
        "-crf", ["crf", "INT", {"default": 23, "min": 0, "max": 100, "step": 1}]
    ],
    "audio_pass": ["-c:a", "libopus"],
    "extension": "webm",
    "environment": {"SVT_LOG": "1"},
    "input_color_depth": "10bit"
}
```

--------------------------------

### LoadAudio Node

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/05-audio-nodes.md

Loads audio from a specified file path or URL. It supports trimming the audio by setting a start time (seek_seconds) and a duration. The node returns the audio data as a dictionary containing the waveform and sample rate, along with the actual duration loaded.

```APIDOC
## LoadAudio Node

### Description
Loads audio from a file path with optional seek/duration trimming.

### Method Signature
```python
def load_audio(
    self,
    audio_file: str,
    seek_seconds: float = 0,
    duration: float = 0
) -> (AUDIO, FLOAT)
```

### Input Parameters

| Parameter | Type | Required | Default | Min | Max | Description |
|-----------|------|----------|---------|-----|-----|-------------|
| `audio_file` | STRING | Yes | — | — | — | Full file path to audio file. Supports relative paths and URLs (via yt-dlp). |
| `seek_seconds` | FLOAT | Optional | 0 | 0 | ∞ | Start time in seconds. 0 = beginning. |
| `duration` | FLOAT | Optional | 0 | 0 | 10000000 | Audio length to load in seconds. 0 = entire file from seek point. |

### Return Values

```python
(AUDIO, FLOAT)
```

| Return | Type | Description |
|--------|------|-------------|
| `audio` | AUDIO | Audio dictionary: `{'waveform': Tensor(1, channels, samples), 'sample_rate': int}` |
| `duration` | FLOAT | Actual duration loaded in seconds. |

### AUDIO Dictionary Format

```python
{
    'waveform': torch.Tensor,  # Shape: (1, num_channels, num_samples), dtype: float32
    'sample_rate': int         # Sample rate in Hz (typical: 44100, 48000)
}
```

### Supported Formats
- WAV, MP3, OGG, M4A, FLAC (based on FFmpeg availability)
- URLs (http/https) — auto-downloaded via yt-dlp

### Usage Example

```python
loader = LoadAudio()

# Load entire audio file
audio, dur = loader.load_audio(
    audio_file="/path/to/music.mp3"
)

# Load 5-second segment starting at 30 seconds
audio, dur = loader.load_audio(
    audio_file="/path/to/music.mp3",
    seek_seconds=30,
    duration=5
)

# Load from URL
audio, dur = loader.load_audio(
    audio_file="https://example.com/audio.mp3",
    seek_seconds=0,
    duration=30
)
```
```

--------------------------------

### Extract Audio from Video via /vhs/viewaudio

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/10-server-endpoints.md

Use this GET request to extract the audio stream from a video file. The 'file' parameter should point to the video file, and 'start_time' can be used to specify an offset within the video.

```http
GET /vhs/viewaudio?file=/path/to/video.mp4&start_time=0
```

--------------------------------

### Tune Memory Usage for Video Loading

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Reduce memory usage by lowering frame_load_cap, using smaller resolutions with custom_width/custom_height, or subsampling frames with select_every_nth. This example sets a 100MB limit per load.

```python
frame_load_cap = 100  # Load 100 frames at a time
custom_width = 256    # 1/4 resolution
select_every_nth = 2  # Every other frame
```

--------------------------------

### Score FFmpeg Binary Suitability

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Scores an FFmpeg binary based on its supported codecs and features. Use this to automatically select the best FFmpeg installation from multiple available options.

```python
def ffmpeg_suitability(path: str) -> int:
    pass
```

--------------------------------

### Lazy Get Audio Function Signature

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/05-audio-nodes.md

Provides a signature for a lazy audio loading function, which defers loading until first access for memory efficiency. It returns a mapping object.

```python
def lazy_get_audio(
    file: str,
    start_time: float = 0,
    duration: float = 0
) -> LazyAudioMap
```

--------------------------------

### Download Video from URL

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Downloads a video from a given URL using yt-dlp or youtube-dl. The function caches downloads and saves them to the ComfyUI temporary directory. Requires yt-dlp/youtube-dl to be installed and the VHS_YTDL environment variable to be set.

```python
# Load video from URL
video_path = try_download_video("https://example.com/video.mp4")
if video_path:
    images, count, audio, info = load_video(video=video_path)
```

--------------------------------

### Get Sorted Directory Files with Filtering

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Returns a sorted list of files from a directory, with options to skip initial files, select every nth file, and filter by extension. Useful for processing image sequences or specific file types.

```python
def get_sorted_dir_files_from_directory(
    directory: str,
    skip_first_images: int = 0,
    select_every_nth: int = 1,
    extensions: Iterable = None
) -> list[str]:
    pass
```

```python
files = get_sorted_dir_files_from_directory(
    directory="/path/to/frames",
    skip_first_images=10,
    select_every_nth=2,
    extensions=[.png, .jpg]
)
# Returns every 2nd PNG/JPG file, skipping first 10
```

--------------------------------

### Get Image Count

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/04-image-latent-nodes.md

Returns the number of items in an image batch. Use this to determine the batch size of your image tensor.

```Python
count = get_image_count(images=images)  # images.shape: (16, 512, 512, 3)
# count: 16
```

--------------------------------

### Specify Video Downloader Path

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Set this variable to point to your preferred video downloader executable, such as yt-dlp or youtube-dl. This is necessary for loading video or audio directly from URLs. The system prioritizes yt-dlp during auto-detection.

```bash
export VHS_YTDL=/usr/bin/yt-dlp
```

--------------------------------

### Lazy Load Audio

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Use this function to get a lazy-loading audio dictionary. Audio data is only loaded when accessed, improving memory efficiency for potential use cases.

```python
def lazy_get_audio(
    file: str,
    start_time: float = 0,
    duration: float = 0
) -> LazyAudioMap:
    pass
```

--------------------------------

### Audio Preview

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/README.md

Serves audio with support for seek and duration.

```APIDOC
## GET /vhs/viewaudio

### Description
Serve audio with specified seek and duration.

### Method
GET

### Endpoint
/vhs/viewaudio

### Parameters
#### Query Parameters
- **file** (string) - Required - Path to the audio file.
- **seek** (string) - Optional - Seek to a specific time in the audio.
- **duration** (string) - Optional - Duration of the audio to serve.
```

--------------------------------

### Register Custom Video Format Directory

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Add a custom directory for video format JSON files in your extension's __init__.py. Custom formats take precedence over built-in ones with the same name.

```python
# In your extension's __init__.py
import folder_paths

# Add custom format directory
folder_paths.folder_names_and_paths["VHS_video_formats"][0].add("/path/to/formats")

# JSON files in directory automatically loaded
```

--------------------------------

### Register Custom Folder Paths

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Registers a custom directory for video formats. This allows the videohelper suite to recognize and use formats from a specified location.

```python
folder_paths.folder_names_and_paths["VHS_video_formats"] = (
    ("/custom/path/to/formats",), 
    {".json"}
)
```

--------------------------------

### Load Images with Batching Options

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/07-image-loading-nodes.md

Loads images with options for batching, skipping initial images, and controlling the loading frequency. Useful for managing large image sequences.

```python
# Load with batching for large sequences
images, masks, count = loader.load_images(
    directory="/data/long_sequence",
    image_load_cap=32,
    skip_first_images=0
)
```

--------------------------------

### Get Audio Function Signature

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/05-audio-nodes.md

Defines the core audio loading function, supporting various formats via FFmpeg. It returns an audio dictionary containing waveform and sample rate.

```python
def get_audio(
    file: str,
    start_time: float = 0,
    duration: float = 0
) -> dict
```

--------------------------------

### BatchManager State Tracking Example

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/06-video-metadata-nodes.md

This snippet demonstrates how the BatchManager tracks the re-queue count to manage batch processing. It resets the manager on the first run (requeue=0) and prints progress on subsequent runs.

```python
def update_batch(self, frames_per_batch, prompt=None, unique_id=None):
    if unique_id is not None and prompt is not None:
        requeue = prompt[unique_id]['inputs'].get('requeue', 0)
    else:
        requeue = 0
    
    if requeue == 0:
        self.reset()  # First run
    else:
        # Subsequent runs
        num_batches = (self.total_frames + self.frames_per_batch - 1) // self.frames_per_batch
        print(f'Meta-Batch {requeue}/{num_batches}')
```

--------------------------------

### Specify Gifski Binary Path

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Provide the file path to the Gifski binary if you want to use it for GIF creation. If this is not set, or Gifski is not found, formats requiring it may be skipped. Gifski generally produces higher quality GIFs than FFmpeg.

```bash
export VHS_GIFSKI=/opt/gifski
```

--------------------------------

### Get Loaded Video Metadata

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/06-video-metadata-nodes.md

Use VideoInfoLoaded to retrieve metadata reflecting any applied transformations. This includes effective frame rate after force_rate, frame count after caps and skips, and dimensions after resizing.

```python
video_node = VideoInfoLoaded()
loaded_fps, loaded_frames, loaded_dur, loaded_w, loaded_h = video_node.get_video_info(video_info)

print(f"Loaded: {loaded_frames} frames at {loaded_fps} fps, {loaded_w}x{loaded_h}")
# Loaded: 16 frames at 8 fps, 512x512
```

--------------------------------

### Get Original Video Metadata

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/06-video-metadata-nodes.md

Use VideoInfoSource to extract the original, unaltered metadata of a video file. This includes the source frame rate, total frame count, duration, width, and height.

```python
video_node = VideoInfoSource()
source_fps, source_frames, source_dur, source_w, source_h = video_node.get_video_info(video_info)

print(f"Source Video: {source_w}x{source_h} at {source_fps} fps")
# Source Video: 1920x1080 at 30 fps
```

--------------------------------

### Full Pipeline: Encode → Process → Decode with VAEDecodeBatched

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/09-vae-batch-nodes.md

Illustrates a complete video processing pipeline using VAEDecodeBatched for decoding. This includes loading video, encoding to latents, processing in latent space, and decoding back to images.

```python
# Load video as images
images, count, _, _ = load_video(video="source.mp4", frame_load_cap=256)

# Encode to latents
encoder = VAEEncodeBatched()
latents = encoder.encode(vae=vae, images=images)
# latents['samples']: (256, 4, 64, 64)

# Process in latent space (e.g., apply transformations)
# ... processing nodes here ...

# Decode back to images
decoder = VAEDecodeBatched()
processed_images = decoder.decode(vae=vae, samples=latents)
# processed_images: (256, 512, 512, 3)

# Combine to video
video = combine_video(images=processed_images, ...)
```

--------------------------------

### try_download_video()

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Attempts to download a video from a given URL using yt-dlp or youtube-dl. It handles caching and saving to the ComfyUI temporary directory.

```APIDOC
## try_download_video()

### Description
Downloads video from URL using yt-dlp/youtube-dl.

### Parameters
#### Path Parameters
- **url** (str) - Required - HTTP(S) URL to download.

### Returns
- File path (str) if download successful
- None if yt-dlp not available or download failed

### Behavior
- Caches downloads (same URL returns cached path)
- Saves to ComfyUI temp directory
- Requires `VHS_YTDL` env var, yt-dlp, or youtube-dl in PATH

### Exceptions
- `CalledProcessError` if download fails

### Example
```python
# Load video from URL
video_path = try_download_video("https://example.com/video.mp4")
if video_path:
    images, count, audio, info = load_video(video=video_path)
```
```

--------------------------------

### Extract Audio from File

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/08-utility-functions.md

Use this function to extract audio data from a given file. Specify start time and duration for precise extraction. Supports various audio and video formats via FFmpeg.

```python
def get_audio(
    file: str,
    start_time: float = 0,
    duration: float = 0,
    **kwargs
) -> dict:
    pass
```

--------------------------------

### VideoCombine Method Signature

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/02-video-combine.md

Shows the signature for the combine_video method, detailing all input parameters and their types.

```python
def combine_video(
    self,
    frame_rate: int,
    loop_count: int,
    images=None,
    latents=None,
    filename_prefix="AnimateDiff",
    format="image/gif",
    pingpong=False,
    save_output=True,
    prompt=None,
    extra_pnginfo=None,
    audio=None,
    unique_id=None,
    manual_format_widgets=None,
    meta_batch=None,
    vae=None,
    **kwargs
) -> (VHS_FILENAMES,)

```

--------------------------------

### Direct VAE Encoding in ComfyUI

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/09-vae-batch-nodes.md

Demonstrates the standard ComfyUI VAE encoding process for a batch of images. This method may fail with large batches due to GPU memory limitations.

```python
# Standard ComfyUI VAE nodes
images = torch.randn(256, 512, 512, 3)
latents = vae.encode(images)  # May fail with large batches
```

--------------------------------

### Invoke Legacy VHS_AUDIO Type

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/11-types-and-formats.md

Demonstrates how to invoke the legacy VHS_AUDIO type, which is a callable returning WAV file bytes. This is deprecated and the modern AUDIO type should be used instead.

```python
vhs_audio: Callable[[], bytes]
```

```python
wav_bytes = vhs_audio()  # Returns WAV file bytes
```

--------------------------------

### Load Images from Absolute Path

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/07-image-loading-nodes.md

Loads images from a specified absolute directory path. Ensure the directory exists and contains image files.

```python
loader = LoadImagesFromDirectoryPath()

# Load from absolute path
images, masks, count = loader.load_images(
    directory="/home/user/animation_frames"
)
```

--------------------------------

### Check yt-dlp Path

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Checks if the yt-dlp executable path is available. If not found, URL downloads will be disabled.

```python
from videohelpersuite.utils import ytdl_path

if ytdl_path is None:
    # URL downloads disabled
```

--------------------------------

### Extend VHSLoadFormats with Custom Presets

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Plugins can add custom load format presets by modifying the nodes.VHSLoadFormats dictionary. These merged with built-in presets.

```python
import nodes  # ComfyUI nodes module

nodes.VHSLoadFormats["MyFormat"] = {
    'target_rate': 24,
    'dim': (16, 0, 1024, 576),
    'frames': (8, 1)
}
```

--------------------------------

### Check FFmpeg Path

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/12-configuration-reference.md

Checks if the FFmpeg executable path is available. If FFmpeg is not found, video and audio operations will fail.

```python
from videohelpersuite.utils import ffmpeg_path

if ffmpeg_path is None:
    # FFmpeg not found, video/audio operations will fail
```

--------------------------------

### LoadVideoFFmpegUpload

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/03-load-video-nodes.md

Loads video from uploaded files using FFmpeg as the backend. This method offers better codec support compared to OpenCV but is generally slower. It accepts the same inputs as LoadVideoUpload and returns the same output types.

```APIDOC
## LoadVideoFFmpegUpload

### Description
Alternative FFmpeg-based video loader from uploaded files. Uses FFmpeg directly instead of OpenCV (cv2). Better codec support but slower.

### Method
Not specified (likely a node execution in a workflow)

### Endpoint
Not applicable (local node execution)

### Parameters
Input is assumed to be from uploaded files, similar to LoadVideoUpload.

### Request Example
Not applicable

### Response
Returns same output types as LoadVideoUpload (video frames/tensors).
```

--------------------------------

### Widget Format Specification

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/11-types-and-formats.md

Defines the structure for additional UI widgets within video format configurations, specifying display name, type, and value constraints.

```json
["display_name", "TYPE", {"default": value, "min": min, "max": max, "step": step}]
```

--------------------------------

### VideoCombine Node

Source: https://github.com/kosinkadink/comfyui-videohelpersuite/blob/main/_autodocs/02-video-combine.md

The VideoCombine node takes a sequence of image frames (or latents) and combines them into a video file. It supports various output formats, audio embedding, ping-pong looping, and saving workflow metadata.

```APIDOC
## VideoCombine Node

### Description
Combines a sequence of image frames into an output video file. Optionally embeds audio, applies ping-pong looping, and saves workflow metadata.

### Method Signature
```python
def combine_video(
    self,
    frame_rate: int,
    loop_count: int,
    images=None,
    latents=None,
    filename_prefix="AnimateDiff",
    format="image/gif",
    pingpong=False,
    save_output=True,
    prompt=None,
    extra_pnginfo=None,
    audio=None,
    unique_id=None,
    manual_format_widgets=None,
    meta_batch=None,
    vae=None,
    **kwargs
) -> (VHS_FILENAMES,)
```

### Input Parameters

#### Required Parameters
- **images** (IMAGE or LATENT) - Required* - Frame sequence to encode. Can be latent tensors which are first decoded.
- **latents** (LATENT) - Required* - Alternative to images; if provided, used for frame data.
- **frame_rate** (INT) - Required - Output playback speed in frames per second (1-60). Higher values result in faster playback and shorter duration.
- **loop_count** (INT) - Required - Number of times the video repeats after the first play (0-100).
- **filename_prefix** (STRING) - Required - Base filename for output. Supports subdirectories: `folder/name`. Supports timestamp substitution: `%date:yyyy-MM-ddThh:mm:ss%`.
- **format** (STRING) - Required - Output format specification. Options: `image/gif`, `image/webp`, `video/*` (FFmpeg formats).

#### Optional Parameters
- **pingpong** (BOOLEAN) - Optional - If True, plays video forward then backward for seamless looping. Reverses frame order on playback.
- **save_output** (BOOLEAN) - Optional - If True, saves to output directory. If False, saves to temp directory.
- **audio** (AUDIO) - Optional - Audio dictionary with `waveform` (torch.Tensor) and `sample_rate` (int). If provided, mixed into output.
- **meta_batch** (VHS_BatchManager) - Optional - Batch manager for orchestrating multi-part encoding across workflow re-queues.
- **vae** (VAE) - Optional - VAE model for decoding latent tensors. If provided, converts latents to images before encoding.
- **manual_format_widgets** (dict) - Optional - Override format widget values programmatically.
- **prompt** (PROMPT) - Hidden - Full workflow prompt dict (used for metadata/workflow embedding).
- **extra_pnginfo** (EXTRA_PNGINFO) - Hidden - Extra PNG metadata (used for workflow embedding).
- **unique_id** (UNIQUE_ID) - Hidden - Unique node ID (used for batch tracking).
- **kwargs** (dict) - Optional - Additional format-specific parameters (e.g., `crf`, `lossless`, `pix_fmt`).

* Either `images` or `latents` must be provided. If both provided, `latents` takes precedence.
```