Decode Cache Helper:
H3DecodeCacheHelper is an optional helper for the Continuum V3.8X2 workflow that can reuse completed VAE decoding results instead of decoding the same video or audio latent data repeatedly. In practical terms, it can make repeated workflow reviews, finalization passes, or parameter adjustments faster when the underlying latent content and VAE model have not changed. Video decode entries are stored in a private process-local disk cache when automatic caching is enabled, while audio decode entries use a limited private RAM cache. The node does not change sampling, unload models, or alter the artistic content of the decode; it focuses only on retaining and reusing complete physical VAE decode results. The cache is specific to the running process and is not designed to reuse files after the application restarts. You can also disable caching entirely or reset the helper cache when VAE weights have been edited in place.
Decode Cache Helper Input Parameters:
cache_mode
This setting controls whether decoded video and audio results are retained for reuse. The available options are Auto, RAM, and Off, with Auto as the default. Auto uses a disk-backed cache for video and a small bounded RAM cache for audio, providing the intended balance between reuse and memory consumption. RAM restricts caching to bounded RAM and does not use the disk cache, which may be useful when disk writes are undesirable but sufficient memory is available. Off uses native decoding without retaining cache entries and clears the helper cache. Choosing a cache mode affects execution time on repeated runs, storage use, and memory use, but it does not change the decoded image or audio content. The value must be one of the three listed options.
ram_budget_mb
This integer sets the additional private RAM retention limit for cached decoded results, measured in MiB although the interface labels the control in megabytes. The default is 256, the minimum is 0, and the maximum is 8192, with increments of 128. This is not a limit for all memory used by the application; it only controls the extra RAM allowance used by this helper for retained cache entries. A value of 0 prevents RAM retention, while a larger value can allow more audio or RAM-mode cache results to remain available for reuse. Increasing it may improve repeated-run performance but can reduce available memory for other parts of your workflow. The setting does not force a decode result to fit in memory; it controls how much cached data the helper is allowed to retain.
disk_budget_gb
This integer sets the process-local disk cache quota in GiB for retained video decode results. The default is 8, the minimum is 0, and the maximum is 128, with increments of 1. A value of 0 prevents cache file writes, while a larger value allows more completed video decodes to remain available for reuse during the current application process. Increasing the quota can reduce repeated video decoding, especially for large or numerous video entries, but it uses disk space. The cache is not reused after the application restarts according to the node description, so this setting is intended for repeated work within one running session rather than permanent storage.
reset_token
This non-negative integer provides a manual way to discard this helper's cache. Its default is 0, the minimum is 0, and the maximum is 2147483647. Increase the value whenever you need to force the helper to treat previously stored results as invalid, particularly after changing VAE weights in place without replacing the VAE object. Keeping the same value allows eligible cached entries to be considered for reuse; changing it triggers a cache reset associated with the new token. This control does not alter the latent samples or VAE itself.
video_samples
This optional LATENT input supplies the Continuum video_latents list for decoding. Each connected entry is decoded as a complete video result before later trimming or seam processing, and the decoded results are returned through the images output in the same entry order. If an entry is missing, the helper preserves that position with an unconnected result rather than duplicating a previous entry. When this input is not connected or contains no entries, the node produces no video results. The corresponding video_vae should be the same native Video VAE used by the existing VAE Decode node so that cached results represent the intended model.
video_vae
This optional VAE input supplies the native Video VAE used to decode video_samples. It is required for meaningful video decoding when video latent entries are connected, and the same Video VAE used by the existing decode stage should be connected here. The selected VAE affects the decoded image content and also determines whether a previously cached result is appropriate for reuse. If you edit VAE weights in place, increase reset_token so old cached results are discarded.
audio_samples
This optional LATENT input supplies the Continuum audio_latents list for independent audio decoding. Each connected entry is decoded separately and returned through the audio output in the same order. Missing entries remain represented as missing positions rather than being replaced by another entry. When this input is not connected or contains no entries, the node produces no audio results. Audio caching is handled independently from video caching, so the presence or absence of audio entries does not require video entries.
audio_vae
This optional VAE input supplies the native Audio VAE used to decode audio_samples. It is required only when audio_samples is connected and contains entries. Connect the same Audio VAE used by the VAE Decode Audio stage so the decoded audio matches the intended workflow. Changes to the audio VAE can make previous cached results unsuitable; increasing reset_token clears the helper cache so the audio is decoded again.
Decode Cache Helper Output Parameters:
images
This IMAGE output contains the decoded video image results produced from video_samples, returned in entry order as a list. Each non-missing latent entry is decoded as a whole before later trim or seam operations, allowing complete results to be reused on subsequent executions when the cache considers them valid. If there are no video samples, the output list is empty; if a video entry is unconnected, its position is preserved as a missing result. The output is intended to connect to the existing finalization stage without changing the surrounding assembly or sampling workflow.
audio
This AUDIO output contains the independently decoded audio results produced from audio_samples, returned in entry order as a list. Cached audio results may be reused according to the selected mode and RAM budget, while uncached entries are decoded normally. If no audio samples are connected, the output list is empty. Missing audio entries remain missing rather than causing the previous audio entry to be copied into their position.
report
This STRING output contains a formatted JSON diagnostic report describing what the helper did. The report includes helper_version, the selected mode, event details for each video and audio entry, and current cache statistics. Entry events can indicate whether an item was unconnected or provide cache and decode status information from the decode service. If cache configuration fails, the report can also include cache_disabled_reason, while the node falls back to native decoding with caching disabled. This report is useful for checking whether repeated runs are using cached results and for diagnosing cache availability or configuration problems.
Decode Cache Helper Usage Tips:
- Use
Autofor the normal Continuum V3.8X2 workflow when you want video results stored on disk and audio results retained in bounded RAM during the current application session. - Connect the unchanged Assembly Plan directly to the finalization stage as described by the node, and use this helper for complete VAE decode reuse rather than changing sampling or model-loading behavior.
- Set
disk_budget_gbto0when you do not want the helper to write cache files. In this configuration, disk-backed video reuse is unavailable even ifcache_modeisAuto. - Use
RAMwhen you want caching without disk writes, but keepram_budget_mbappropriate for the available memory on your system. A value of0disables RAM retention and can prevent useful reuse. - Increase
ram_budget_mbordisk_budget_gbwhen repeated runs contain large decoded videos or many entries and the report shows that results are being removed or not retained because the quota is too small. - Increase
reset_tokenafter changing VAE weights in place. This prevents the helper from reusing decoded results made with the previous VAE state. - Use
Offwhen testing native decoding, troubleshooting unexpected cache behavior, or ensuring that the current run does not retain helper cache entries. - Keep the Video VAE connected to
video_vaeand the Audio VAE connected toaudio_vae. The node treats the two streams independently, so each latent stream should use its matching native VAE. - Inspect the JSON in
reportafter configuring the node. It provides per-entry events and cache statistics that can show whether entries were decoded, reused, left unconnected, or affected by a cache configuration problem. - Remember that the cache is process-local and is not intended to survive an application restart. Set the budgets based on the current session rather than expecting the cache to become a permanent library of decoded media.
Decode Cache Helper Common Errors and Solutions:
cache_mode expects one value, not a list batch
- Explanation: The control inputs are single settings, but the node received multiple values for
cache_mode. This can happen when a list or batch is connected to a setting that expects only one selection. - Solution: Connect a single
cache_modevalue and choose exactly one option:Auto,RAM, orOff.
ram_budget_mb expects one value, not a list batch
- Explanation: The RAM budget received a list of values instead of one integer setting.
- Solution: Provide one integer value between
0and8192, normally using the node's control widget rather than a batched connection.
disk_budget_gb expects one value, not a list batch
- Explanation: The disk quota received multiple values, but the node can configure only one disk budget for the operation.
- Solution: Provide one integer from
0to128. Use0when cache file writes should be disabled.
reset_token expects one value, not a list batch
- Explanation: The reset control was given a list instead of one integer.
- Solution: Connect or enter one non-negative integer. Increase that single value when you need to discard the helper's existing cache.
invalid cache settings
- Explanation: At least one cache setting is invalid. The mode may not be
Auto,RAM, orOff, or one of the budget values may be negative. - Solution: Select a valid cache mode, set
ram_budget_mbfrom0to8192, setdisk_budget_gbfrom0to128, and keepreset_tokenbetween0and2147483647.
Cache unavailable; native decode: ...
- Explanation: The helper could not configure its cache, so it disabled caching and continued with native decoding. The text after the colon gives the underlying reason, which may relate to the cache location, quota, permissions, or another store configuration issue.
- Solution: Check the detailed reason in the node log and in the
cache_disabled_reasonfield of thereportoutput. Confirm that the application can access its cache location, reduce the requested budget if necessary, or setcache_modetoOffwhen you intentionally want native decoding without caching.
diagnostic_error
- Explanation: The helper could not collect cache statistics after processing. Decoding may still have completed, but the report contains a
diagnostic_errorfield instead of normal cache statistics. - Solution: Review the diagnostic text in the
reportoutput, verify that the cache storage is accessible, and retry withcache_modeset toOffto determine whether the issue is limited to cache reporting.
Missing video output or unconnected video entry
- Explanation: A video latent entry was absent or
video_sampleswas not connected. The helper intentionally keeps the missing position instead of duplicating a previous decoded entry. - Solution: Connect the Continuum
video_latentslist tovideo_samples, verify that it contains the expected entries, and connect the matching Video VAE tovideo_vae.
Missing audio output or unconnected audio entry
- Explanation: An audio latent entry was absent or
audio_sampleswas not connected. The node does not invent audio or copy a previous entry into the missing position. - Solution: Connect the Continuum
audio_latentslist toaudio_sampleswhen audio is required, and connect the matching Audio VAE toaudio_vae.
Video or audio decode result is not as expected after a VAE change
- Explanation: The helper may still consider an earlier cached decode valid when VAE weights were edited in place.
- Solution: Increase
reset_tokento discard the helper's cache, then run the decode again with the intended Video VAE or Audio VAE connected.
Cache does not persist after restarting the application
- Explanation: This helper uses a private process-local cache, and its automatic mode does not reuse cache files after the application restarts.
- Solution: Treat the cache as a session optimization. Re-run the workflow after restarting, and configure the budgets again if the node settings were not retained by your workflow.
