sok.file_operations.music_operations
File operations for music media.
This module handles:
- Detection and extraction of information from audio file names
- Reading metadata (ID3, FLAC tags, etc.)
- Automatic track renaming
- Organization by artist/album
MusicFileOperations
class MusicFileOperationsBases: FileOperations, FileParsingMixin, FileValidationMixin, FileListOrganizerMixin
File operations for music files.
Provides methods to extract metadata from audio filenames, read embedded tags (ID3, FLAC), organize by artist/album, and rename tracks according to music conventions.
Sourcesupported_extensionsproperty
List[str]
Return list of supported audio file extensions.
batch_target
def batch_target( media_item: MediaItem, file_path: Path, alone: bool,) -> Tuple[List[str], str]:Folders and file name of a track of a batch.
When the service gives no track number, the number of the file tags is used if the file is on the same album.
Parameters
| Name | Type | Description |
|---|---|---|
media_item | MediaItem | |
file_path | Path | |
alone | bool |
extract_info_from_filename
def extract_info_from_filename(filename: str) -> Dict[str, Any]:Extract information from a audio 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_audio_files
def find_audio_files(directory: str, recursive: bool = True) -> List[str]:Find all audio files in a directory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
directory | str | Directory to scan. | |
recursive | bool | True | Enable recursive search. |
Returns
List[str]List of audio file paths.
find_files
def find_files(directory: str, recursive: bool = True) -> List[str]:Unified alias for find_audio_files.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
directory | str | ||
recursive | bool | True |
format_track
def format_track( track: Any, extension: str, track_number: Optional[int] = None,) -> List[str]:Folders and file name of a track, from the music format setting.
The format, "{artist} - {album}/{track} - {title}" by default, has one part per folder and the file name last. A value the track does not have is left out with its separator: without a track number, "{track} - {title}" gives "Title".
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
track | Any | The Track found online. | |
extension | str | Extension of the file, with its dot. | |
track_number | Optional[int] | None | Number to use when the track has none. |
Returns
List[str]The folder names, then the file name.
generate_new_filename
def generate_new_filename( media_item: Optional[MediaItem], original_filename: str,) -> str:Generate a new filename for an audio track.
For a track found online, the file part of the music format of the settings (see format_track). Otherwise, from the original name: '01 - Track Title.mp3'.
Parameters
| Name | Type | Description |
|---|---|---|
media_item | Optional[MediaItem] | The media item (Album or Track). |
original_filename | str | Original filename. |
Returns
strNew filename.
organize_by_artist_album
def organize_by_artist_album( source_path: str, dest_path: str, use_metadata: bool = True, dry_run: bool = False,) -> Dict[str, Any]:Organize audio files by Artist/Album.
Created structure: Artist/Album (Year)/tracks
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
source_path | str | Source folder. | |
dest_path | str | Destination folder. | |
use_metadata | bool | True | Use file metadata. |
dry_run | bool | False | Simulation mode. |
Returns
Dict[str, Any]Organization report.
read_metadata
def read_metadata(file_path: str) -> Dict[str, Any]:Read metadata from an audio file.
Reads ID3, FLAC tags, and other embedded metadata.
Parameters
| Name | Type | Description |
|---|---|---|
file_path | str | Audio file path. |
Returns
Dict[str, Any]Dictionary with read metadata.
Attributes
| Name | Value |
|---|---|
logger | logging.getLogger(__name__) |