File Sequence

License: PRO+ (Professional Edition or higher)
Plugin Type: File Action
Author: Diskover Data, Inc.

Overview

The File Sequence file action analyzes directories to identify file sequences—groups of files that follow a numbered naming pattern, like the individual frames that make up a video. It's particularly valuable in media and entertainment workflows where thousands of image files (DPX, EXR, TIFF, PNG) represent frames of video content that need to be validated before post-production work begins.

Beyond sequence detection, this file action also flags potentially corrupted or incomplete files based on a configurable size threshold, helping you catch problems before they impact your workflow.

Key Features

Intelligent Sequence Detection — Automatically groups files into sequences using pattern recognition with regex matching, collapsing thousands of individual frame files into logical groupings
Parallel Processing — Uses ThreadPoolExecutor with configurable worker count for improved performance on large directories
Dual Lookup Methods — Choose between real-time filesystem scanning for current accuracy or Elasticsearch index queries for faster analysis of previously indexed content
Bad File Detection — Identifies potentially corrupted files based on minimum size thresholds, flagging zero-byte or undersized files for review
Gap Detection — Automatically creates separate sequence entries when gaps are detected in file numbering, making it easy to identify missing frames
Flexible Extension Filtering — Focus analysis on specific file types (e.g., .exr,.dpx) to exclude irrelevant files
Real-Time Progress Tracking — Monitor analysis progress through the web interface with live updates via AJAX polling
LRU Caching — Implements directory scan caching to avoid repeated filesystem operations during analysis
Export Capabilities — Download results in JSON format for automation or plain text for reports and documentation

Use Cases

VFX and Animation Production
Verify image sequence integrity across render farm outputs. Identify missing frames in DPX or EXR sequences before color grading or compositing begins. Detect incomplete renders that may have failed silently during overnight batch processing.

Post-Production Quality Control
Detect frame drops or corrupted frames in delivered media packages. Validate that sequences match expected frame ranges before ingesting into editorial systems. Flag zero-byte or undersized frames that indicate write failures or disk corruption.

Media Asset Management
Organize and categorize sequences versus individual files for proper archival and retrieval. Generate sequence-aware reports that collapse thousands of individual frame files into logical sequence groupings. Support metadata enrichment workflows by identifying sequence patterns in legacy archives.

Storage Optimization
Identify incomplete sequences that consume storage but lack production value. Find orphaned sequence fragments from aborted renders. Support cleanup workflows by providing clear sequence boundary detection.

Understanding File Sequences

If you're new to working with image sequences, this section explains the concepts this file action works with.

What is a File Sequence?

In video and film production, a "file sequence" is a series of individual image files that, when played in order, create motion video. Each file represents a single frame. For example, a 10-second clip at 24 frames per second consists of 240 individual image files.

These files follow a consistent naming pattern with incrementing frame numbers:

Example Pattern	Description
`shot001.0001.exr` through `shot001.0240.exr`	Zero-padded 4-digit frame numbers
`render_001.dpx` through `render_240.dpx`	Zero-padded 3-digit frame numbers
`frame1.tif` through `frame240.tif`	Non-padded frame numbers

Common Sequence Formats

Format	Extension	Typical Use
OpenEXR	`.exr`	VFX compositing, HDR imagery
DPX	`.dpx`	Film scanning, color grading
TIFF	`.tif`, `.tiff`	High-quality stills, print
JPEG	`.jpg`, `.jpeg`	Previews, proxy sequences
PNG	`.png`	Graphics with transparency

Why Sequence Detection Matters

Without sequence detection, a directory containing 10,000 frame files appears as 10,000 individual items. Sequence detection groups these into logical units like "shot001.[0001-5000].exr" and "shot002.[0001-5000].exr"—making it immediately clear you have two sequences of 5,000 frames each.

Supported Naming Conventions

This file action uses regex pattern matching to detect sequences. The following naming conventions are supported:

Pattern	Example	Description
Dot separator	`file.0001.ext`	Common in VFX pipelines
Underscore separator	`file_0001.ext`	Alternative separator style
No separator	`file0001.ext`	Direct number suffix

Gap Handling

When gaps are detected in a sequence (e.g., missing frames), the file action creates separate sequence entries for each continuous range. For example:

Files present: frames 1-5 and 8-15

Output:

✓ SEQUENCE: render.[0001-0005].exr
✓ SEQUENCE: render.[0008-0015].exr

This makes it immediately clear which frame ranges exist and where gaps occur, helping you identify missing content at a glance.

Requirements

Diskover Requirements

Requirement	Details
Diskover Version	Compatible with current Diskover releases
License Tier	PRO+ (Professional Edition or higher)
Task Worker	Celery worker must be running and accessible
Python Version	Python 3.9 or higher

External Requirements

This file action is self-contained within Diskover and has no external Python dependencies beyond the Diskover core libraries.

Installation & Setup

Installation

The File Sequence file action is installed via RPM package:

dnf install diskover-file-actions-filesequence

Service Restarts

After installation, restart the required services:

systemctl restart diskover-admin
systemctl restart celery

Note: Restart diskover-admin on the Diskover Web host. Restart celery on all Diskover Task Worker host(s).

Verify Installation

Log into Diskover Web
Navigate to any indexed directory
Select one or more directories
Click the Actions menu — you should see File Sequence as an option

Configuration

Configuration is managed through the Diskover Admin interface.

Location: Diskover Admin → Configuration → Plugins → File Actions → File Sequence

Configuration Options

Setting	Default	Description
`extensions`	(empty)	Comma-separated list of file extensions to analyze (e.g., `.dpx,.exr,.jpg`). Leave empty to analyze all files. Extensions should include the leading dot.
`min_size`	`1024`	Minimum file size in bytes. Files smaller than this threshold are flagged as "potentially bad," indicating possible corruption or incomplete writes.
`lookup_method`	`storage`	How files are discovered: `storage` scans the filesystem directly for real-time accuracy; `index` queries the Elasticsearch index for faster processing of previously indexed content.

Configuration Examples

VFX EXR Sequence Validation
For validating OpenEXR renders where valid frames are typically at least 10KB:

Setting	Value
extensions	`.exr`
min_size	`10240`
lookup_method	`storage`

DPX Film Scan Verification
For checking DPX film scans where frames are typically several megabytes:

Setting	Value
extensions	`.dpx`
min_size	`4194304`
lookup_method	`storage`

Multi-Format Sequence Discovery
For discovering all common sequence formats across a large indexed archive:

Setting	Value
extensions	`.dpx,.exr,.tif,.tiff,.jpg,.jpeg,.png`
min_size	`1024`
lookup_method	`index`

Choosing a Lookup Method

Method	Best For	Trade-offs
`storage`	Recent renders, newly ingested media, real-time validation	Slower on very large directories; requires filesystem access
`index`	Large-scale reporting, archived content, faster analysis	Results reflect index state at last crawl time

Usage Guide

Basic Workflow

Step 1: Select Directories

In Diskover Web, navigate to the directories you want to analyze. Use the checkboxes to select one or more directories containing potential file sequences.

Tip: You can select multiple directories to analyze an entire project structure in one operation.

Step 2: Launch the File Action

Click the Actions menu in the toolbar and select File Sequence.

Step 3: Review and Configure

The configuration interface displays:

The paths you selected for analysis
Configuration options (extensions, minimum size, lookup method)
The assigned worker queue

Review the settings and adjust if needed for your specific use case.

Step 4: Submit the Analysis

Click Submit to begin processing. You'll be redirected to a progress tracking page.

Step 5: Monitor Progress

The progress page shows:

A progress bar with percentage complete
Status messages describing the current operation
A Cancel button if you need to abort

Step 6: Review Results

When analysis completes, results are organized into sections:

Sequences Found — Detected file sequences displayed in range notation:

✓ SEQUENCE: /renders/shot001/beauty.[0001-0100].exr
✓ SEQUENCE: /renders/shot001/depth.[0001-0100].exr

Individual Files — Files that don't match any sequence pattern:

• /renders/shot001/reference.jpg
• /renders/shot001/notes.txt

Potentially Bad Files — Files flagged for review based on size threshold:

⚠ /renders/shot001/beauty.0047.exr (0 bytes)
⚠ /renders/shot001/beauty.0048.exr (512 bytes)

Summary Statistics — Aggregate metrics including total files analyzed, sequences found, sequence coverage percentage, and performance metrics (processing time, files per second).

Step 7: Export Results (Optional)

Use the export buttons to download results:

JSON — Structured data for automated processing or integration
TXT — Human-readable report for documentation or sharing

Common Tasks

Validating Render Farm Output

When renders complete overnight, validate the output before artists begin work:

Select the render output directories
Set extensions to match your render format (e.g., .exr)
Set min_size to a reasonable threshold for your format (e.g., 10240 for EXR)
Use storage lookup for real-time accuracy
Review results for any flagged bad files or unexpected gaps in sequences

Auditing a Media Library

For periodic audits of large media archives:

Select top-level directories to scan
Leave extensions empty to discover all file types
Use index lookup for faster processing
Export results as JSON for record-keeping or further analysis

Checking Incoming Deliverables

When receiving media from vendors or external sources:

Select the delivery directories
Configure extensions based on expected formats
Set min_size based on expected file sizes for the format
Use storage lookup for accurate current state
Flag any bad files for follow-up with the vendor

Troubleshooting

Common Issues

Issue	Cause	Solution
No sequences found	Files don't follow a recognizable naming pattern	Verify files have incrementing numbers in their names (e.g., `file.0001.exr`). Supported patterns include `file.0001.ext`, `file_0001.ext`, and `file0001.ext`. Files without numeric components cannot form sequences.
No sequences found	Extension filter too restrictive	Check that your configured extensions match the actual file extensions (including case). Try leaving extensions empty to analyze all files.
Analysis takes too long	Very large directories with many files	Try using `index` lookup method for faster processing, or process directories in smaller batches.
Progress bar stuck	Task still processing but throttled updates	Check Celery worker logs to confirm the task is running. Large directories may take time between progress updates. Ensure “Assigned Worker” has access to the files being analyzed and that the worker can communicate with Diskover Web.
Bad files not detected	min_size threshold too low	Increase the min_size value to match typical valid file sizes for your format.
Export fails	Task not yet complete	Wait for the analysis to fully complete before attempting to export results.
Memory issues with large directories	Very large directories consuming too much memory	For directories with millions of files, consider using the `index` lookup method instead of `storage`. Split large directories into smaller analysis jobs.

Debug Logging

For detailed troubleshooting, check the following log files:

Log	Location	Purpose
Diskover Admin	`/var/log/diskover/diskover-admin.log`	Web interface and task submission
Celery Worker	`/var/log/celery/worker.log`	Task execution and processing
Nginx	`/var/log/nginx/error.log`	Web server errors

To enable verbose logging, set the log level to DEBUG in your configuration.

Common Error Messages

Error Message	Resolution
"Worker not set in session"	Re-authenticate to Diskover Web and ensure worker assignment is configured properly.
"Directory does not exist"	Verify the target path exists and the worker has read access to the storage location.
"Failed to connect to Elasticsearch"	When using `index` lookup method, ensure Elasticsearch is running and accessible. Try switching to `storage` lookup as a workaround.
"Task completed but results could not be retrieved"	Verify the Celery result backend (Redis) is properly configured and running.
"Error scanning directory"	Check worker permissions on the target storage. Ensure the Celery service account has read access.
"Task timeout"	The analysis exceeded time limits. Try processing fewer directories per submission or increase Celery task timeout settings.

Support

Documentation: https://docs.diskoverdata.com
Support Portal: https://support.diskoverdata.com

Last Updated: February 2026
Diskover Data, Inc.