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 VideoFileOperationsBases: 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.
Sourcesupported_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
| Name | Type | Description |
|---|---|---|
file_path | str | Video file path. |
Returns
Dict[str, Any]Detailed video information.
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
| Name | Type | Default | Description |
|---|---|---|---|
media_item | MediaItem | The media item; only a Series has season folders. | |
filename | str | The name of the file, which gives its season. | |
base_path | str | The folder of the series (or of the movie). | |
on_disk | bool | True | Look for an existing season folder in base_path. |
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
| Name | Type | Description |
|---|---|---|
filename | str | File name to parse. |
Returns
Dict[str, Any]Dictionary with extracted information.
find_files
def find_files(directory: str, recursive: bool = True) -> List[str]:Unified alias for find_video_files.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
directory | str | ||
recursive | bool | True |
find_video_files
def find_video_files(directory: str, recursive: bool = True) -> List[str]:Find all video files in a directory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
directory | str | Directory to scan. | |
recursive | bool | True | Enable recursive search in subfolders. |
Returns
List[str]List of video file paths.
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
| Name | Type | Description |
|---|---|---|
media_item | MediaItem | The media item. |
original_filename | str | Original filename. |
Returns
strNew filename.
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
| Name | Type | Default | Description |
|---|---|---|---|
source_path | str | Source folder. | |
dest_path | str | Destination folder. | |
media_item | MediaItem | The media item. | |
dry_run | bool | False | If True, simulate without making changes. |
progress_callback | Optional[Callable[[int, int, str], None]] | None | Function called with (current, total, filename) to report progress. |
Returns
Dict[str, Any]Organization report (moved files, errors, etc.).
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
| Name | Type | Default | Description |
|---|---|---|---|
files | List[Path] | List of files to organize. | |
dest_path | str | Destination folder. | |
media_item | MediaItem | The media item. | |
dry_run | bool | False | If True, simulate without making changes. |
progress_callback | Optional[Callable[[int, int, str], None]] | None | Function called with (current, total, filename). |
Returns
Dict[str, Any]Organization report.
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
| Name | Type | Default | Description |
|---|---|---|---|
mappings | List[tuple] | List of (Path, Movie) pairs. Files without a movie are reported as errors. | |
dest_path | str | Destination folder. | |
dry_run | bool | False | If True, simulate without making changes. |
progress_callback | Optional[Callable[[int, int, str], None]] | None | Called with (current, total, filename). |
Returns
Dict[str, Any]Organization report with moved/errors/skipped.
Attributes
| Name | Value |
|---|---|
logger | logging.getLogger(__name__) |