Media

media

Defines helper functions to perform asynchronous file operations within the HOST_MEDIA_PATH directory

Paths

• BASE_PATH is the media root (HOST_MEDIA_PATH)

• TEMP_PATH and PROFILES_PATH are its temp and profiles subdirectories

• Operations take destinations relative to BASE_PATH, and get_relative_path converts an absolute path back to that format

Modal Paths

• When using the modal transcription backend, the server uploads input files to (and downloads processed files from) an ephemeral per-job volume shared between it and the Modal container running the job (See modal_processing.worker)

• Both the server and the container pass the in-volume paths in which they've stored files so that the server's media handling doesn't depend on the container sharing its file system layout

• The media-relative path from get_relative_path is only used as the path in which the server stores files inside the modal volume to maintain consistency

PARTIAL_SUFFIX = '.mirumoji-partial' module-attribute

Reserved marker naming a media file that is still being written

Writes land on a uniquely named <stem>.<token>.mirumoji-partial<ext> sibling and are atomically renamed into place, so a reader never observes a partially written file and two concurrent writes never share a temporary

atomic_output(path)

Yields a temporary sibling to write to, renamed into path on success

Producers That Write Their Own Output

The helpers in this module stream their own bytes, so they build the temporary themselves. FFMPEG and genanki instead take a destination path and write it over many seconds

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	The final destination path	required

Yields:

Type	Description
Path	The temporary sibling to write to

Raises:

Type	Description
StorageError	If the finished output cannot be renamed into place

clean_temp(check=False) async

Deletes everything in the temp directory and recreates it

Parameters:

Name	Type	Description	Default
check	bool	When True, raise on failure. Otherwise log and skip	False

Raises:

Type	Description
StorageError	If the directory cannot be cleared and check is True

copy_file(src, dest_relative) async

Copies a file to a destination relative to the media directory

Parameters:

Name	Type	Description	Default
src	str | PathLike[str]	Absolute source path of the file to copy	required
dest_relative	str | PathLike[str]	Destination path, relative to the media directory	required

Returns:

Type	Description
Path	The absolute path to the new file

Raises:

Type	Description
StorageError	If the file cannot be copied

delete_dir(dir_path_relative) async

Deletes a directory located relative to the media directory

Parameters:

Name	Type	Description	Default
dir_path_relative	str | PathLike[str]	Path of the directory to delete, relative to the media directory	required

Raises:

Type	Description
StorageError	If the directory cannot be deleted

delete_file(file_path_relative, check=False) async

Deletes a single file located relative to the media directory

Parameters:

Name	Type	Description	Default
file_path_relative	str | PathLike[str]	Path of the file to delete, relative to the media directory	required
check	bool	When True, raise on failure. Otherwise log and skip	False

Raises:

Type	Description
StorageError	If the file cannot be deleted and check is True

get_profile_dir(profile_id, subfolder)

Creates and returns a profile-specific subdirectory

Parameters:

Name	Type	Description	Default
profile_id	str	ID of the profile	required
subfolder	str	Subfolder within the profile's directory	required

Returns:

Type	Description
Path	The absolute path to the profile-specific subdirectory

get_relative_path(full_path)

Converts an absolute path into one relative to the media directory

Modal File Transfer

• This relative form is used as the file's path within the per-job ephemeral Modal volume when the server uploads it

• This is done so that the in-volume layout of media_files mirrors the HOST_MEDIA_PATH directory

• See modal_processing.worker for more information on this

Parameters:

Name	Type	Description	Default
full_path	str | PathLike[str]	Absolute path inside the media directory	required

Returns:

Type	Description
Path	The path relative to BASE_PATH

Raises:

Type	Description
InvalidMediaPathError	If full_path is not inside the media directory

get_temp_dir(name)

Creates and returns a named directory inside TEMP_PATH

Parameters:

Name	Type	Description	Default
name	str	Name of the temporary directory	required

Returns:

Type	Description
Path	The absolute path to the created temporary directory

init_storage()

Creates the media directory tree (base, temp, profiles) if missing

Meant to be called once on application startup so module import stays free of filesystem side effects

move_file(src, dest_relative) async

Moves a file to a destination relative to the media directory

Parameters:

Name	Type	Description	Default
src	str | PathLike[str]	Absolute source path of the file to move	required
dest_relative	str | PathLike[str]	Destination path, relative to the media directory	required

Returns:

Type	Description
Path	The absolute path to the moved file

Raises:

Type	Description
StorageError	If the file cannot be moved

partial_path(path)

Builds a unique temporary sibling path for an atomic write of path

The random token keeps two concurrent writes to the same destination from sharing a temporary file, and the reserved marker keeps the Modal-host volume syncer from mirroring it

The Marker Sits Before The Extension

• FFMPEG picks its muxer from the output's extension and takes no format flag here, so the temporary has to keep the real one

• Appending the marker would leave ffmpeg unable to infer a container

Parameters:

Name	Type	Description	Default
path	Path	The final destination path	required

Returns:

Type	Description
Path	A unique <stem>.<token>.mirumoji-partial<ext> sibling of path

save_upload_file(request, output_path, description=None) async

Saves a FastAPI.Request.stream to the file system by reading and writing the streamed chunks to output_path while reporting the progress on a themed transfer bar with description as its label

Parameters:

Name	Type	Description	Default
request	Request	The FastAPI.Request object	required
output_path	str | PathLike[str]	File path in which to save the stream	required
description	str | None	Optional label for the progress bar. When None, defaults to f"Saving File To {output_path}"	None

Returns:

Type	Description
Path	output_path, if the file was written successfully

Raises:

Type	Description
ClientDisconnect	If the client cancelled the upload
UploadError	If the upload fails for any reason

save_upload_object(upload, output_path) async

Saves a FastAPI.UploadFile (a multipart file part) to the file system by streaming it to output_path in chunks

Difference From save_upload_file

save_upload_file is used for large raw-body streamed uploads while save_upload_object is used for multipart uploads (File(...)) where the file travels alongside form metadata

Parameters:

Name	Type	Description	Default
upload	UploadFile	The multipart file part to save	required
output_path	str | PathLike[str]	File path in which to save it	required

Returns:

Type	Description
Path	output_path, if the file was written successfully

Raises:

Type	Description
UploadError	If the upload fails for any reason

write_file(file_path_relative, content) async

Writes text content to a file relative to the media directory, creating parent directories as needed

Atomic Overwrite

The content is written to a temporary sibling and then atomically renamed into place, so it replaces any existing file in one step and a reader (or the Modal-host volume syncer) never sees a half-written file

Parameters:

Name	Type	Description	Default
file_path_relative	str | PathLike[str]	Path of the file to write, relative to the media directory	required
content	str	Text content to write to the file	required

Returns:

Type	Description
Path	The absolute path to the written file

Raises:

Type	Description
StorageError	If the file cannot be written