Skip to content

sok.file_operations.video_operations

File operations for video media (movies, series, documentaries).

This module handles:

  • Detection and extraction of information from file names
  • Automatic renaming according to conventions
  • Organization and creation of folder structure
  • Quality and language detection

VideoFileOperations

class VideoFileOperations

Bases: FileParsingMixin, FileValidationMixin

File operations for video media (movies, series, documentaries).

Provides methods to extract metadata from video filenames, organize files into folder structures, and rename according to media conventions.

Source

supported_extensionsproperty

List[str]

Return list of supported video file extensions.

detect_video_info

def detect_video_info(file_path: str) -> Dict[str, Any]:

Detect video information (resolution, codec, duration, etc.).

Parameters

NameTypeDescription
file_pathstrVideo file path.

Returns

  • Dict[str, Any]Detailed video information.
Source

episode_folder

def episode_folder(
media_item: MediaItem,
filename: str,
base_path: str,
on_disk: bool = True,
) -> str:

The folder of a file of a series: its season folder, an existing one first ("Saison 01"), or the base folder without a season.

Parameters

NameTypeDefaultDescription
media_itemMediaItemThe media item; only a Series has season folders.
filenamestrThe name of the file, which gives its season.
base_pathstrThe folder of the series (or of the movie).
on_diskboolTrueLook for an existing season folder in base_path.
Source

extract_info_from_filename

def extract_info_from_filename(filename: str) -> Dict[str, Any]:

Extract information from a video filename.

The input patterns of the settings are tried first (sok.core.name_patterns); the name is otherwise read by the rules of _parse_filename. "pattern" is the pattern that matched, if any.

Parameters

NameTypeDescription
filenamestrFile name to parse.

Returns

  • Dict[str, Any]Dictionary with extracted information.
Source

find_files

def find_files(directory: str, recursive: bool = True) -> List[str]:

Unified alias for find_video_files.

Parameters

NameTypeDefaultDescription
directorystr
recursiveboolTrue
Source

find_video_files

def find_video_files(directory: str, recursive: bool = True) -> List[str]:

Find all video files in a directory.

Parameters

NameTypeDefaultDescription
directorystrDirectory to scan.
recursiveboolTrueEnable recursive search in subfolders.

Returns

  • List[str]List of video file paths.
Source

generate_new_filename

def generate_new_filename(media_item: MediaItem, original_filename: str) -> str:

Generate a new filename for a video.

Uses the custom format defined in settings.

Default series format: '{title} S{season}E{episode} {episode_title}' Default movie format: '{title} ({year})'

Parameters

NameTypeDescription
media_itemMediaItemThe media item.
original_filenamestrOriginal filename.

Returns

  • strNew filename.
Source

organize_files

def organize_files(
source_path: str,
dest_path: str,
media_item: MediaItem,
dry_run: bool = False,
progress_callback: Optional[Callable[[int, int, str], None]] = None,
) -> Dict[str, Any]:

Organize video files into a folder structure.

For series: Series Name/Season 01/files For movies: Movie Name (2020)/file

Parameters

NameTypeDefaultDescription
source_pathstrSource folder.
dest_pathstrDestination folder.
media_itemMediaItemThe media item.
dry_runboolFalseIf True, simulate without making changes.
progress_callbackOptional[Callable[[int, int, str], None]]NoneFunction called with (current, total, filename) to report progress.

Returns

  • Dict[str, Any]Organization report (moved files, errors, etc.).
Source

organize_files_list

def organize_files_list(
files: List[Path],
dest_path: str,
media_item: MediaItem,
dry_run: bool = False,
progress_callback: Optional[Callable[[int, int, str], None]] = None,
) -> Dict[str, Any]:

Organize a list of video files into a folder structure.

Unlike organize_files which scans a folder, this method directly processes a list of files (which can come from multiple folders).

Parameters

NameTypeDefaultDescription
filesList[Path]List of files to organize.
dest_pathstrDestination folder.
media_itemMediaItemThe media item.
dry_runboolFalseIf True, simulate without making changes.
progress_callbackOptional[Callable[[int, int, str], None]]NoneFunction called with (current, total, filename).

Returns

  • Dict[str, Any]Organization report.
Source

organize_movies_batch

def organize_movies_batch(
mappings: List[tuple],
dest_path: str,
dry_run: bool = False,
progress_callback: Optional[Callable[[int, int, str], None]] = None,
) -> Dict[str, Any]:

Organize a list of movie files, each with its own Movie metadata.

Unlike organize_files_list, this method accepts per-file media items, enabling batch renaming where each file maps to a different movie.

Parameters

NameTypeDefaultDescription
mappingsList[tuple]List of (Path, Movie) pairs. Files without a movie are reported as errors.
dest_pathstrDestination folder.
dry_runboolFalseIf True, simulate without making changes.
progress_callbackOptional[Callable[[int, int, str], None]]NoneCalled with (current, total, filename).

Returns

  • Dict[str, Any]Organization report with moved/errors/skipped.
Source

Attributes

NameValue
loggerlogging.getLogger(__name__)
Built with Kiln