Fix TypeError when loading image sequences

[talmo]

Summary

Fixes a TypeError that occurred when loading SLEAP files containing image sequences (e.g., from DeepLabCut projects) in the GUI.

Problem

After a recent update, opening certain .slp files in the GUI resulted in:

TypeError: _path_exists: path should be string, bytes, os.PathLike or integer, not list

Error location: sleap/sleap_io_adaptors/lf_labels_utils.py:817

Root Cause

The sleap-io library's Video.filename attribute can be either:

• str - for regular video files (mp4, avi, etc.)
• list[str] - for image sequences (multiple PNG/JPG files)

The video callback code assumed filename was always a single value. When processing image sequences, this created a list of lists, causing os.path.exists() to fail with a TypeError.

Example Issue

# Old code
filenames = [item.filename for item in video_list]
# For image sequences: filenames = [[path1, path2, ...], [path1, path2, ...]]

missing = [not os.path.exists(filename) for filename in filenames]
# TypeError! os.path.exists() can't accept a list

Solution

Modified the video callback in lf_labels_utils.py to handle both single files and image sequences:

1. Detect video type: Track whether each video is an image sequence
2. Use representative file: For image sequences, use the first file to check existence
3. Preserve structure: Maintain the full list of filenames for later updates
4. Update correctly: When paths change, update the directory for all files in the sequence

Code Changes

Before:

filenames = [item.filename for item in video_list]
missing = [not os.path.exists(filename) for filename in filenames]

After:

filenames = []
is_image_sequence = []
for item in video_list:
    if isinstance(item.filename, (list, tuple)):
        is_image_sequence.append(True)
        filenames.append(item.filename[0] if item.filename else None)
    else:
        is_image_sequence.append(False)
        filenames.append(item.filename)

missing = []
for filename in filenames:
    if filename is None:
        missing.append(True)
    else:
        filename_str = str(filename)
        missing.append(not os.path.exists(filename_str))

Also updated the filename restoration logic to preserve image sequence lists when updating paths.

Testing

Tested with a DeepLabCut project file containing:

• 42 image sequence videos
• 756 labeled frames

Results:

• ✅ Successfully loads without errors
• ✅ Correctly handles image sequences
• ✅ Maintains compatibility with regular video files
• ✅ Path correction functionality works for image sequences

Investigation

Detailed investigation materials are available in scratch/video_path_bug_investigation/:

• Root cause analysis
• Test scripts validating the fix
• Complete documentation of the issue and solution

Impact

• Fixes loading of DeepLabCut image sequence projects
• Maintains compatibility with regular video files
• Preserves path correction functionality for image sequences
• No breaking changes to existing functionality

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 61.90476% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.46%. Comparing base (ed0635c) to head (4b097dc).

Files with missing lines	Patch %	Lines
sleap/sleap_io_adaptors/lf_labels_utils.py	61.90%	8 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #2452   +/-   ##
========================================
  Coverage    59.45%   59.46%           
========================================
  Files           68       68           
  Lines        13216    13234   +18     
========================================
+ Hits          7858     7870   +12     
- Misses        5358     5364    +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.