Deep-Live-Cam Temporary Frame Management and Cleanup Workflow: Complete Technical Guide

Deep-Live-Cam extracts video frames into a temporary directory, processes them as individual PNG files, re-encodes the results into video, and automatically removes temporary resources through a coordinated pipeline managed by modules/core.py and modules/utilities.py.

The temporary frame management and cleanup workflow in Deep-Live-Cam enables efficient video face-swapping by handling video data as discrete image sequences rather than continuous streams. This architecture, implemented in the hacksider/Deep-Live-Cam repository, minimizes memory usage during heavy AI processing while ensuring no residual files remain after execution unless explicitly requested.

The 9-Step Temporary Frame Lifecycle

Deep-Live-Cam processes every video through a strict lifecycle coordinated by utility functions in modules/utilities.py and orchestrated by the main loop in modules/core.py.

Step 1: Creating the Temporary Workspace

The function create_temp() (lines 41-44 in modules/utilities.py) generates a dedicated workspace at <video-folder>/temp/<video-name>. This directory serves as the sandbox for all intermediate PNG files and temporary video outputs.

Step 2: Resolving the Directory Path

Before extraction begins, get_temp_directory_path() (lines 19-23) constructs the absolute path by parsing the target video filename. This ensures that parallel processing of different videos never conflicts on the filesystem.

Step 3: Extracting Frames to PNG

The extract_frames() function (lines 64-77) invokes ffmpeg to decompose the input video into sequentially numbered PNG files (%04d.png). This creates a discrete frame sequence that frame processors can handle individually.

Step 4: Indexing Frame Files

Once extraction completes, get_temp_frame_paths() (lines 14-16) scans the temporary directory and returns a sorted list of all PNG file paths. This list becomes the processing queue for the frame processors.

Step 5: Processing Frames with Enabled Processors

The orchestration logic passes the frame list to process_video() in modules/processors/frame/core.py (lines 95-101). Internally, multi_process_frame distributes the workload across parallel threads—processing one frame per batch to maintain low memory overhead while maximizing throughput.

Step 6: Encoding Processed Frames to Video

After all frames are modified, create_video() (lines 80-88 in modules/utilities.py) re-assembles the PNG sequence into a video file named temp.mp4. The function automatically selects either hardware-accelerated or software encoders based on system capabilities.

Step 7: Restoring Original Audio (Optional)

If the user sets keep_audio to true, restore_audio() (lines 92-108) copies the original audio track from the source video onto the newly encoded output using ffmpeg mapping.

Step 8: Moving Final Output

When audio restoration is skipped, move_temp() (lines 46-52) performs an atomic rename operation, moving temp.mp4 from the temporary directory to the user-specified output_path.

Step 9: Cleaning Up Temporary Resources

The clean_temp() function (lines 54-60) recursively deletes the temporary directory and its parent folder if empty. This executes unconditionally after successful processing unless the global flag keep_frames is set to True.

Abort Handling and Emergency Cleanup

If the user terminates the application prematurely, the destroy() callback in modules/core.py (lines 81-84) immediately invokes clean_temp() to prevent orphaned temporary files from consuming disk space.

Orchestration Logic in modules/core.py

The high-level coordination occurs in modules/core.py, where the main processing loop sequences the temporary frame operations:

# 1️⃣ Temp creation & frame extraction

if not modules.globals.map_faces:
    create_temp(modules.globals.target_path)          # ← creates temp folder

    extract_frames(modules.globals.target_path)       # ← writes PNGs

# 2️⃣ Gather frame list

temp_frame_paths = get_temp_frame_paths(modules.globals.target_path)

# 3️⃣ Process each frame with enabled processors

for frame_processor in get_frame_processors_modules(modules.globals.frame_processors):
    frame_processor.process_video(modules.globals.source_path, temp_frame_paths)

# 4️⃣ Encode video (with optional fps detection)

if modules.globals.keep_fps:
    fps = detect_fps(modules.globals.target_path)
    create_video(modules.globals.target_path, fps)
else:
    create_video(modules.globals.target_path)

# 5️⃣ Audio handling / move output

if modules.globals.keep_audio:
    restore_audio(modules.globals.target_path, modules.globals.output_path)
else:
    move_temp(modules.globals.target_path, modules.globals.output_path)

# 6️⃣ Cleanup

clean_temp(modules.globals.target_path)               # ← delete temp files

Reference: Lines 26-33, 35-42, 48-58, 61-73, and 81-84 in modules/core.py.

Practical Code Examples

Running the Complete Pipeline

Use the high-level core.run() interface to execute the entire temporary frame workflow with configurable cleanup options:

from modules import globals, core

globals.target_path = "input/video.mp4"      # source video

globals.source_path = "input/face.jpg"       # reference face image

globals.output_path = "output/result.mp4"
globals.frame_processors = ["face_swapper"]  # enable the face‑swap processor

globals.keep_frames = False                  # delete temp frames after finish

globals.keep_audio = True
globals.keep_fps = True
globals.execution_threads = 8                # parallel processing

core.run()                                   # starts the whole workflow

Manual Frame Lifecycle Management

For custom processing pipelines, explicitly control temporary resource creation and cleanup:

from modules.utilities import (
    create_temp, extract_frames, get_temp_frame_paths,
    clean_temp, get_temp_directory_path
)
from modules.processors.frame.face_swapper import process_frame_v2
import cv2

video = "input/video.mp4"
create_temp(video)                     # ① create temp folder

extract_frames(video)                  # ② extract PNGs

paths = get_temp_frame_paths(video)    # ③ list PNG files

for png in paths:
    img = cv2.imread(png)
    result = process_frame_v2(img, png)   # ④ custom frame processing

    cv2.imwrite(png, result)              # overwrite with processed frame

# … now you could call create_video(...) and restore_audio(...)

clean_temp(video)                     # ⑨ delete temp folder

Key Implementation Files

The temporary frame management system spans three critical modules:

• modules/utilities.py – Implements directory creation (create_temp), frame extraction (extract_frames), video encoding (create_video), audio restoration (restore_audio), and cleanup utilities (clean_temp, move_temp).

• modules/core.py – Orchestrates the end-to-end workflow, managing the sequence from temporary directory initialization through final cleanup, including the destroy() handler for abort scenarios.

• modules/processors/frame/core.py – Provides the parallel processing infrastructure via process_video() and multi_process_frame, which operate on the temporary PNG files enumerated by the utilities module.

Summary

• Deep-Live-Cam extracts all video frames to <video-folder>/temp/<video-name> as PNG files before processing begins.
• The frame processors consume these temporary files in parallel batches to maintain low memory usage.
• ffmpeg handles both the initial frame extraction and final video encoding, with optional audio track preservation via restore_audio().
• Cleanup occurs automatically through clean_temp() unless keep_frames is enabled, and emergency cleanup is guaranteed by the destroy() handler in modules/core.py.

Frequently Asked Questions

Where does Deep-Live-Cam store temporary frames during processing?

Deep-Live-Cam stores frames in a subdirectory named temp inside the source video's folder, specifically at <video-folder>/temp/<video-name>, as constructed by get_temp_directory_path() in modules/utilities.py. Each frame is saved as a sequentially numbered PNG file (%04d.png) by the extract_frames() function.

How does Deep-Live-Cam clean up temporary files after processing?

The clean_temp() function in modules/utilities.py (lines 54-60) recursively deletes the temporary directory and removes its parent folder if empty. This executes automatically after successful video encoding or when the destroy() callback triggers an emergency cleanup during application termination.

Can I keep the extracted PNG frames after video processing completes?

Yes. Set globals.keep_frames = True before invoking core.run(). When this flag is enabled, clean_temp() skips the deletion step, preserving the temporary directory containing all extracted and processed PNG files for inspection or reuse.

What happens to temporary files if I abort the processing mid-way?

The destroy() function in modules/core.py (lines 81-84) captures application exit signals and immediately calls clean_temp() to remove the temporary directory. This ensures that partial frame extractions or incomplete processing runs do not leave orphaned files consuming disk space.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}