stouputils 1.12.1__py3-none-any.whl

stouputils/applications/automatic_docs.pyi

@@ -0,0 +1,106 @@
+from ..continuous_delivery import version_to_float as version_to_float
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error, simple_cache as simple_cache
+from ..io import clean_path as clean_path, json_dump as json_dump, super_open as super_open
+from ..print import info as info
+from collections.abc import Callable as Callable
+
+REQUIREMENTS: list[str]
+
+def check_dependencies(html_theme: str) -> None:
+    ''' Check for each requirement if it is installed.
+
+\tArgs:
+\t\thtml_theme (str): HTML theme to use for the documentation, to check if it is installed (e.g. "breeze", "pydata_sphinx_theme", "furo", etc.)
+\t'''
+def get_sphinx_conf_content(project: str, project_dir: str, author: str, current_version: str, copyright: str, html_logo: str, html_favicon: str, html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', version_list: list[str] | None = None, skip_undocumented: bool = True) -> str:
+    """ Get the content of the Sphinx configuration file.
+
+\tArgs:
+\t\tproject           (str):              Name of the project
+\t\tproject_dir       (str):              Path to the project directory
+\t\tauthor            (str):              Author of the project
+\t\tcurrent_version   (str):              Current version
+\t\tcopyright         (str):              Copyright information
+\t\thtml_logo         (str):              URL to the logo
+\t\thtml_favicon      (str):              URL to the favicon
+\t\tgithub_user       (str):              GitHub username
+\t\tgithub_repo       (str):              GitHub repository name
+\t\tversion_list      (list[str] | None): List of versions. Defaults to None
+\t\tskip_undocumented (bool):             Whether to skip undocumented members. Defaults to True
+
+\tReturns:
+\t\tstr: Content of the Sphinx configuration file
+\t"""
+def get_versions_from_github(github_user: str, github_repo: str, recent_minor_versions: int = 2) -> list[str]:
+    """ Get list of versions from GitHub gh-pages branch.
+\tOnly shows detailed versions for the last N minor versions, and keeps only
+\tthe latest patch version for older minor versions.
+
+\tArgs:
+\t\tgithub_user             (str): GitHub username
+\t\tgithub_repo             (str): GitHub repository name
+\t\trecent_minor_versions   (int): Number of recent minor versions to show all patches for (-1 for all).
+
+\tReturns:
+\t\tlist[str]: List of versions, with 'latest' as first element
+\t"""
+def markdown_to_rst(markdown_content: str) -> str:
+    """ Convert markdown content to RST format.
+
+\tArgs:
+\t\tmarkdown_content (str): Markdown content
+
+\tReturns:
+\t\tstr: RST content
+\t"""
+def generate_index_rst(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str, int], list[str]] = ..., recent_minor_versions: int = 2) -> None:
+    """ Generate index.rst from README.md content.
+
+\tArgs:
+\t\treadme_path            (str): Path to the README.md file
+\t\tindex_path             (str): Path where index.rst should be created
+\t\tproject                (str): Name of the project
+\t\tgithub_user            (str): GitHub username
+\t\tgithub_repo            (str): GitHub repository name
+\t\tget_versions_function  (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
+\t\trecent_minor_versions  (int): Number of recent minor versions to show all patches for. Defaults to 2
+\t"""
+def generate_documentation(source_dir: str, modules_dir: str, project_dir: str, build_dir: str) -> None:
+    """ Generate documentation using Sphinx.
+
+\tArgs:
+\t\tsource_dir        (str): Source directory
+\t\tmodules_dir       (str): Modules directory
+\t\tproject_dir       (str): Project directory
+\t\tbuild_dir         (str): Build directory
+\t"""
+def generate_redirect_html(filepath: str) -> None:
+    """ Generate HTML content for redirect page.
+
+\tArgs:
+\t\tfilepath (str): Path to the file where the HTML content should be written
+\t"""
+def update_documentation(root_path: str, project: str, project_dir: str = '', author: str = 'Author', copyright: str = '2025, Author', html_logo: str = '', html_favicon: str = '', html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', version: str | None = None, skip_undocumented: bool = True, recent_minor_versions: int = 2, get_versions_function: Callable[[str, str, int], list[str]] = ..., generate_index_function: Callable[..., None] = ..., generate_docs_function: Callable[..., None] = ..., generate_redirect_function: Callable[[str], None] = ..., get_conf_content_function: Callable[..., str] = ...) -> None:
+    ''' Update the Sphinx documentation.
+
+\tArgs:
+\t\troot_path                  (str): Root path of the project
+\t\tproject                    (str): Name of the project
+\t\tproject_dir                (str): Path to the project directory (to be used with generate_docs_function)
+\t\tauthor                     (str): Author of the project
+\t\tcopyright                  (str): Copyright information
+\t\thtml_logo                  (str): URL to the logo
+\t\thtml_favicon               (str): URL to the favicon
+\t\thtml_theme                 (str): Theme to use for the documentation. Defaults to "breeze"
+\t\tgithub_user                (str): GitHub username
+\t\tgithub_repo                (str): GitHub repository name
+\t\tversion                    (str | None): Version to build documentation for (e.g. "1.0.0", defaults to "latest")
+\t\tskip_undocumented          (bool): Whether to skip undocumented members. Defaults to True
+\t\trecent_minor_versions      (int): Number of recent minor versions to show all patches for. Defaults to 2
+
+\t\tget_versions_function      (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
+\t\tgenerate_index_function    (Callable[..., None]): Function to generate index.rst
+\t\tgenerate_docs_function     (Callable[..., None]): Function to generate documentation
+\t\tgenerate_redirect_function (Callable[[str], None]): Function to create redirect file
+\t\tget_conf_content_function  (Callable[..., str]): Function to get Sphinx conf.py content
+\t'''

stouputils/applications/upscaler/__init__.py

@@ -0,0 +1,39 @@
+"""
+This module provides utilities for upscaling images and videos using waifu2x-ncnn-vulkan (by default).
+
+It includes functions to upscale individual images, batches of images in a folder,
+and videos by processing them frame by frame. It also handles configuration and
+installation of required dependencies.
+
+.. raw:: html
+
+	<video width="100%" height="auto" controls>
+			<source src="https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/applications/upscaler.mp4" type="video/mp4">
+			Your browser does not support the video tag.
+	</video>
+
+Example of script:
+
+.. code-block:: python
+
+	# Imports
+	import stouputils.applications.upscaler as app
+	from stouputils.io import get_root_path
+
+	# Constants
+	ROOT: str = get_root_path(__file__) + "/upscaler"
+	INPUT_FOLDER: str = f"{ROOT}/input"
+	PROGRESS_FOLDER: str = f"{ROOT}/progress"
+	OUTPUT_FOLDER: str = f"{ROOT}/output"
+
+	# Main
+	if __name__ == "__main__":
+		app.video_upscaler_cli(INPUT_FOLDER, PROGRESS_FOLDER, OUTPUT_FOLDER)
+"""
+# ruff: noqa: F403
+
+# Imports
+from .config import *
+from .image import *
+from .video import *
+

stouputils/applications/upscaler/__init__.pyi

@@ -0,0 +1,3 @@
+from .config import *
+from .image import *
+from .video import *

stouputils/applications/upscaler/config.py

@@ -0,0 +1,128 @@
+"""
+This module provides configuration settings and constants for the upscaler application.
+
+It defines the URLs for downloading dependencies like waifu2x-ncnn-vulkan and FFmpeg,
+and provides a Config class with settings for upscaling operations, including output quality,
+bitrates, executable paths, and command-line arguments for the underlying tools.
+
+Configuration options include:
+- Image quality settings (JPG quality)
+- Video encoding parameters (bitrate, codec, etc.)
+- Paths to external binaries (FFmpeg, waifu2x-ncnn-vulkan)
+- Command-line arguments for upscaling and video processing
+"""
+# Constants
+WAIFU2X_NCNN_VULKAN_RELEASES: dict[str, str] = {
+	"Windows": "https://github.com/nihui/waifu2x-ncnn-vulkan/releases/download/20220728/waifu2x-ncnn-vulkan-20220728-windows.zip",
+	"Linux": "https://github.com/nihui/waifu2x-ncnn-vulkan/releases/download/20220728/waifu2x-ncnn-vulkan-20220728-ubuntu.zip",
+	"Darwin": "https://github.com/nihui/waifu2x-ncnn-vulkan/releases/download/20220728/waifu2x-ncnn-vulkan-20220728-macos.zip"
+}
+""" URLs to download waifu2x-ncnn-vulkan from for each common platform. """
+FFMPEG_RELEASES: dict[str, str] = {
+	"Windows": "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip",
+	"Linux": "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl.tar.xz",
+	"Darwin": "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-macos64-gpl.tar.xz"
+}
+""" URLs to download FFmpeg from for each common platform. """
+YOUTUBE_BITRATE_RECOMMENDATIONS: dict[str, dict[str, dict[int, int]]] = {
+	"SDR": {
+		"standard": {  # Standard Frame Rate (24, 25, 30)
+			4320: 160000,  # 8K - 160 Mbps
+			2160: 45000,   # 4K - 45 Mbps
+			1440: 16000,   # 2K - 16 Mbps
+			1080: 8000,    # 1080p - 8 Mbps
+			720: 5000,     # 720p - 5 Mbps
+			480: 2500,     # 480p - 2.5 Mbps
+			0: 1000        # 360p or lower - 1 Mbps
+		},
+		"high": {  # High Frame Rate (48, 50, 60)
+			4320: 240000,  # 8K - 240 Mbps
+			2160: 68000,   # 4K - 68 Mbps
+			1440: 24000,   # 2K - 24 Mbps
+			1080: 12000,   # 1080p - 12 Mbps
+			720: 7500,     # 720p - 7.5 Mbps
+			480: 4000,     # 480p - 4 Mbps
+			0: 1500        # 360p or lower - 1.5 Mbps
+		}
+	},
+	"HDR": {
+		"standard": {  # Standard Frame Rate (24, 25, 30)
+			4320: 200000,  # 8K - 200 Mbps
+			2160: 56000,   # 4K - 56 Mbps
+			1440: 20000,   # 2K - 20 Mbps
+			1080: 10000,   # 1080p - 10 Mbps
+			0: 6500        # 720p or lower - 6.5 Mbps
+		},
+		"high": {  # High Frame Rate (48, 50, 60)
+			4320: 300000,  # 8K - 300 Mbps
+			2160: 85000,   # 4K - 85 Mbps
+			1440: 30000,   # 2K - 30 Mbps
+			1080: 15000,   # 1080p - 15 Mbps
+			0: 9500        # 720p or lower - 9.5 Mbps
+		}
+	}
+}
+""" YouTube bitrate recommendations for different resolutions and frame rates.
+
+This dictionary contains recommended bitrates for YouTube uploads based on:
+- SDR vs HDR content
+- Standard frame rate (24, 25, 30 fps) vs high frame rate (48, 50, 60 fps)
+- Video resolution (from 360p up to 8K)
+
+The values are in kbps (kilobits per second).
+
+Source: https://support.google.com/youtube/answer/1722171
+"""
+
+# Configuration class
+class Config:
+	""" Configuration class for the upscaler. """
+	JPG_QUALITY: int = 95
+	""" JPG quality for the output images. (Range: 0-100) """
+
+	VIDEO_FINAL_BITRATE: int = -1
+	""" Video final bitrate for the output video. -1 for YouTube recommended bitrate based on the video resolution. """
+
+	FFMPEG_EXECUTABLE: str = "ffmpeg"
+	""" Path to the ffmpeg executable, default is "ffmpeg" in the PATH. """
+
+	FFMPEG_ARGS: tuple[str, ...] = (
+		"-c:a", "copy",         # Copy the audio without re-encoding
+		"-c:v", "hevc_nvenc",   # Encode the video
+		"-map", "0:v:0",        # Map the first input -i (frames) as video
+		"-map", "1:a:0?",       # Map the second input -i (sound) as audio, with '?' to ignore if no audio stream
+		"-preset", "slow",      # Set the encoding preset to slow (slower but better quality)
+		"-y",					# Overwrite the output file if it exists
+	)
+	""" Additional arguments sent to the ffmpeg executable when calling subprocess.run(). """
+
+	FFPROBE_EXECUTABLE: str = "ffprobe"
+	""" Path to the ffprobe executable, default is "ffprobe" in the PATH. Used to get the framerate of the video. """
+
+	FFMPEG_CHECK_HELP_TEXT: str = "usage: ffmpeg [options]"
+	""" If this text is present in the output of the ffmpeg executable, it means it's installed correctly. """
+
+	UPSCALER_EXECUTABLE: str = "waifu2x-ncnn-vulkan"
+	""" Path to the upscaler executable, default is "waifu2x-ncnn-vulkan" in the PATH. """
+
+	UPSCALER_ARGS: tuple[str, ...] = (
+		"-i", "INPUT_PATH",     # Input file path
+		"-o", "OUTPUT_PATH",    # Output file path
+		"-s", "UPSCALE_RATIO",  # Upscaling ratio
+		"-n", "3",              # Noise level
+	)
+	""" Arguments sent to the upscaler executable when calling subprocess.run(). """
+
+	UPSCALER_EXECUTABLE_HELP_TEXT: str = "Usage: waifu2x-ncnn-vulkan -i"
+	""" If this text is present in the output of the upscaler executable, it means it's installed correctly. """
+
+	SLIGHTLY_FASTER_MODE: bool = False
+	""" If True, the upscaler executable will be called once, which is slightly faster but you can't see the progress. """
+
+	# Variables
+	upscaler_executable_checked: bool = False
+	""" Whether the upscaler executable has been checked for. """
+
+	ffmpeg_executable_checked: bool = False
+	""" Whether the ffmpeg executable has been checked for. """
+

stouputils/applications/upscaler/config.pyi

@@ -0,0 +1,18 @@
+WAIFU2X_NCNN_VULKAN_RELEASES: dict[str, str]
+FFMPEG_RELEASES: dict[str, str]
+YOUTUBE_BITRATE_RECOMMENDATIONS: dict[str, dict[str, dict[int, int]]]
+
+class Config:
+    """ Configuration class for the upscaler. """
+    JPG_QUALITY: int
+    VIDEO_FINAL_BITRATE: int
+    FFMPEG_EXECUTABLE: str
+    FFMPEG_ARGS: tuple[str, ...]
+    FFPROBE_EXECUTABLE: str
+    FFMPEG_CHECK_HELP_TEXT: str
+    UPSCALER_EXECUTABLE: str
+    UPSCALER_ARGS: tuple[str, ...]
+    UPSCALER_EXECUTABLE_HELP_TEXT: str
+    SLIGHTLY_FASTER_MODE: bool
+    upscaler_executable_checked: bool
+    ffmpeg_executable_checked: bool

stouputils/applications/upscaler/image.py

@@ -0,0 +1,247 @@
+"""
+This module provides utility functions for upscaling images using waifu2x-ncnn-vulkan.
+
+It includes functions to upscale individual images, batches of images in a folder,
+and handle intermediate operations like converting between image formats.
+The module also manages temporary directories for partial processing and tracks
+progress of batch operations.
+
+Main functionalities:
+
+- Converting frames between image formats (PNG to JPG)
+- Upscaling individual images with configurable upscale ratio
+- Batch processing folders of images with progress tracking
+- Handling already processed images to resume interrupted operations
+
+Example usage:
+
+.. code-block:: python
+
+    from stouputils.applications.upscaler import upscale, upscale_folder
+
+    # Upscale a single image
+    upscale("input.jpg", "output.jpg", 2)
+
+    # Upscale a folder of images
+    upscale_folder("input_folder", "output_folder", 2)
+"""
+
+# Imports
+import os
+import shutil
+import subprocess
+from tempfile import TemporaryDirectory
+
+from PIL import Image
+
+from ...installer import check_executable
+from ...io import clean_path
+from ...parallel import multithreading
+from ...print import colored_for_loop, debug, info
+from .config import WAIFU2X_NCNN_VULKAN_RELEASES, Config
+
+
+# Function to convert a PNG frame to JPG format
+def convert_frame(frame_path: str, delete_png: bool = True) -> None:
+	""" Convert a PNG frame to JPG format to take less space.
+
+	Args:
+		frame_path  (str):   Path to the PNG frame to convert.
+		delete_png  (bool):  Whether to delete the original PNG file after conversion.
+
+	Returns:
+		None: This function doesn't return anything.
+
+	Example:
+		.. code-block:: python
+
+			> convert_frame("input.png", delete_png=True)
+			> # input.png will be converted to input.jpg and the original file will be deleted
+
+			> convert_frame("input.png", delete_png=False)
+			> # input.png will be converted to input.jpg and the original file will be kept
+	"""
+	if frame_path.endswith(".png"):
+		with Image.open(frame_path) as img:
+			img.save(frame_path.replace(".png", ".jpg"), quality=Config.JPG_QUALITY)
+		if delete_png:
+			os.remove(frame_path)
+
+
+# Function to get all frames in a folder
+def get_all_files(folder: str, suffix: str | tuple[str, ...] = "") -> list[str]:
+	""" Get all files paths in a folder, with a specific suffix if provided.
+
+	Args:
+		folder     (str):                    Path to the folder containing the files.
+		suffix     (str | tuple[str, ...]):  Suffix of the files to get (e.g. ".png", ".jpg", etc.).
+
+	Returns:
+		list[str]: List of all files paths in the folder.
+
+	Example:
+		>>> files: list[str] = get_all_files("some_folder", ".png")
+		>>> len(files)
+		0
+	"""
+	if not os.path.exists(folder):
+		return []
+	return [f"{folder}/{f}" for f in os.listdir(folder) if f.endswith(suffix)]
+
+
+# Function to create a temporary directory with not upscaled images
+def create_temp_dir_for_not_upscaled(input_path: str, output_path: str) -> TemporaryDirectory[str] | None:
+    """ Creates a temporary directory containing only images that haven't been upscaled yet.
+
+    Args:
+        input_path  (str):  Path to the folder containing input images.
+        output_path (str):  Path to the folder where upscaled images are saved.
+
+    Returns:
+        TemporaryDirectory[str] | None: A temporary directory object if there are images to process,
+                                        None if all images are already upscaled.
+    """
+    # Get all input images and the not upscaled images
+    all_inputs: list[str] = get_all_files(input_path)
+    not_upscaled_images: list[str] = [x for x in all_inputs if not os.path.exists(f"{output_path}/{os.path.basename(x)}")]
+
+    # If all images or none are already upscaled, return None
+    if len(not_upscaled_images) == 0 or (len(not_upscaled_images) == len(all_inputs)):
+        return None
+
+    # Create a temporary directory and copy the not upscaled images to it
+    temp_dir: TemporaryDirectory[str] = TemporaryDirectory()
+    debug(f"Creating temporary directory to process {len(not_upscaled_images)} images: {temp_dir.name}")
+    for image in not_upscaled_images:
+        shutil.copyfile(image, f"{temp_dir.name}/{os.path.basename(image)}")
+    return temp_dir
+
+
+# Helper function to check if the upscaler executable is installed
+def check_upscaler_executable() -> None:
+	if not Config.upscaler_executable_checked:
+		check_executable(Config.UPSCALER_EXECUTABLE, Config.UPSCALER_EXECUTABLE_HELP_TEXT, WAIFU2X_NCNN_VULKAN_RELEASES)
+		Config.upscaler_executable_checked = True
+
+
+# Function to upscale an image
+def upscale(input_path: str, output_path: str, upscale_ratio: int) -> None:
+	""" Upscale an input image (or a directory of images) with the upscaler executable.
+
+	Args:
+		input_path     (str):  Path to the image to upscale (or a directory).
+		output_path    (str):  Path to the output image (or a directory).
+		upscale_ratio  (int):  Upscaling ratio.
+
+	Example:
+		.. code-block:: python
+
+			> upscale("folder", "folder", 2)
+			Traceback (most recent call last):
+				...
+			AssertionError: Input and output paths cannot be the same, got 'folder'
+
+			> upscale("stouputils", "stouputils/output.jpg", 2)
+			Traceback (most recent call last):
+				...
+			AssertionError: If input is a directory, output must be a directory too, got 'stouputils/output.jpg'
+
+
+			> upscale("input.jpg", "output.jpg", 2)
+			> # The input.jpg will be upscaled to output.jpg with a ratio of 2
+
+			> upscale("input_folder", "output_folder", 2)
+			> # The input_folder will be upscaled to output_folder with a ratio of 2
+	"""
+	check_upscaler_executable()
+	is_input_dir: bool = os.path.isdir(input_path)
+	is_output_dir: bool = os.path.isdir(output_path)
+
+	# Assertions
+	assert input_path != output_path, f"Input and output paths cannot be the same, got '{input_path}'"
+	invalid_dir_combination: bool = is_input_dir == True and is_output_dir == False  # noqa: E712
+	assert not invalid_dir_combination, f"If input is a directory, output must be a directory too, got '{output_path}'"
+
+	# Convert output_path to a file path if it's a directory
+	if is_output_dir and not is_input_dir:
+
+		# Needs to be a PNG file to be converted to JPG later
+		output_file_name: str = os.path.basename(input_path).replace(".jpg", ".png")
+		output_path = clean_path(f"{output_path}/{output_file_name}")
+		is_output_dir = False
+
+	# If both input and output are folders, and there are images already upscaled in the output folder,
+	# Then create a temporary folder with not upscaled images
+	temp_dir: TemporaryDirectory[str] | None = None
+	if is_input_dir and is_output_dir:
+		temp_dir = create_temp_dir_for_not_upscaled(input_path, output_path)
+		if temp_dir:
+			input_path = temp_dir.name
+
+	# Build the command and run it
+	cmd: list[str] = [Config.UPSCALER_EXECUTABLE, *Config.UPSCALER_ARGS]
+	cmd[cmd.index("INPUT_PATH")] = input_path	          # Replace the input path
+	cmd[cmd.index("OUTPUT_PATH")] = output_path	          # Replace the output path
+	cmd[cmd.index("UPSCALE_RATIO")] = str(upscale_ratio)  # Replace the upscaled ratio (if using waifu2x-ncnn-vulkan)
+	subprocess.run(cmd, capture_output=True)
+
+	# If the input was a temporary folder, delete it
+	if temp_dir:
+		temp_dir.cleanup()
+
+	# Convert the output frames to JPG format
+	if not is_output_dir:
+		convert_frame(output_path)
+	else:
+		frames_to_convert: list[str] = get_all_files(output_path, ".png")
+		if frames_to_convert:
+			multithreading(convert_frame, frames_to_convert, desc="Converting frames to JPG format")
+
+
+# Function to upscale multiple images
+def upscale_images(images: list[str], output_folder: str, upscale_ratio: int, desc: str = "Upscaling images") -> None:
+	""" Upscale multiple images from a list.
+
+	Args:
+		images        (list[str]): List of paths to the images to upscale.
+		output_folder (str):       Path to the output folder where the upscaled images will be saved.
+		upscale_ratio (int):       Upscaling ratio.
+		desc          (str):       Description of the function execution displayed in the progress bar.
+			No progress bar will be displayed if desc is empty.
+
+	Returns:
+		None: This function doesn't return anything.
+	"""
+	for image_path in (colored_for_loop(images, desc=desc) if desc != "" else images):
+		upscale(image_path, output_folder, upscale_ratio)
+
+# Function to upscale a folder of images
+def upscale_folder(
+	input_folder: str,
+	output_folder: str,
+	upscale_ratio: int,
+	slightly_faster_mode: bool = True,
+	desc: str = "Upscaling folder"
+) -> None:
+	""" Upscale all images in a folder.
+
+	Args:
+		input_folder          (str):   Path to the input folder containing the images to upscale.
+		output_folder         (str):   Path to the output folder where the upscaled images will be saved.
+		upscale_ratio         (int):   Upscaling ratio.
+		slightly_faster_mode  (bool):  Whether to use the slightly faster mode (no progress bar),
+			one call to the upscaler executable.
+		desc                  (str):   Description of the function execution displayed in the progress bar.
+			No progress bar will be displayed if desc is empty.
+
+	Returns:
+		None: This function doesn't return anything.
+	"""
+	info(f"Upscaling '{input_folder}' to '{output_folder}' with a ratio of {upscale_ratio}...")
+	if slightly_faster_mode:
+		upscale(input_folder, output_folder, upscale_ratio)
+	else:
+		inputs: list[str] = get_all_files(input_folder)
+		not_upscaled_images: list[str] = [x for x in inputs if not os.path.exists(f"{output_folder}/{os.path.basename(x)}")]
+		upscale_images(not_upscaled_images, output_folder, upscale_ratio, desc=desc)
+

stouputils/applications/upscaler/image.pyi

@@ -0,0 +1,109 @@
+from ...installer import check_executable as check_executable
+from ...io import clean_path as clean_path
+from ...parallel import multithreading as multithreading
+from ...print import colored_for_loop as colored_for_loop, debug as debug, info as info
+from .config import Config as Config, WAIFU2X_NCNN_VULKAN_RELEASES as WAIFU2X_NCNN_VULKAN_RELEASES
+from tempfile import TemporaryDirectory
+
+def convert_frame(frame_path: str, delete_png: bool = True) -> None:
+    ''' Convert a PNG frame to JPG format to take less space.
+
+\tArgs:
+\t\tframe_path  (str):   Path to the PNG frame to convert.
+\t\tdelete_png  (bool):  Whether to delete the original PNG file after conversion.
+
+\tReturns:
+\t\tNone: This function doesn\'t return anything.
+
+\tExample:
+\t\t.. code-block:: python
+
+\t\t\t> convert_frame("input.png", delete_png=True)
+\t\t\t> # input.png will be converted to input.jpg and the original file will be deleted
+
+\t\t\t> convert_frame("input.png", delete_png=False)
+\t\t\t> # input.png will be converted to input.jpg and the original file will be kept
+\t'''
+def get_all_files(folder: str, suffix: str | tuple[str, ...] = '') -> list[str]:
+    ''' Get all files paths in a folder, with a specific suffix if provided.
+
+\tArgs:
+\t\tfolder     (str):                    Path to the folder containing the files.
+\t\tsuffix     (str | tuple[str, ...]):  Suffix of the files to get (e.g. ".png", ".jpg", etc.).
+
+\tReturns:
+\t\tlist[str]: List of all files paths in the folder.
+
+\tExample:
+\t\t>>> files: list[str] = get_all_files("some_folder", ".png")
+\t\t>>> len(files)
+\t\t0
+\t'''
+def create_temp_dir_for_not_upscaled(input_path: str, output_path: str) -> TemporaryDirectory[str] | None:
+    """ Creates a temporary directory containing only images that haven't been upscaled yet.
+
+    Args:
+        input_path  (str):  Path to the folder containing input images.
+        output_path (str):  Path to the folder where upscaled images are saved.
+
+    Returns:
+        TemporaryDirectory[str] | None: A temporary directory object if there are images to process,
+                                        None if all images are already upscaled.
+    """
+def check_upscaler_executable() -> None: ...
+def upscale(input_path: str, output_path: str, upscale_ratio: int) -> None:
+    ''' Upscale an input image (or a directory of images) with the upscaler executable.
+
+\tArgs:
+\t\tinput_path     (str):  Path to the image to upscale (or a directory).
+\t\toutput_path    (str):  Path to the output image (or a directory).
+\t\tupscale_ratio  (int):  Upscaling ratio.
+
+\tExample:
+\t\t.. code-block:: python
+
+\t\t\t> upscale("folder", "folder", 2)
+\t\t\tTraceback (most recent call last):
+\t\t\t\t...
+\t\t\tAssertionError: Input and output paths cannot be the same, got \'folder\'
+
+\t\t\t> upscale("stouputils", "stouputils/output.jpg", 2)
+\t\t\tTraceback (most recent call last):
+\t\t\t\t...
+\t\t\tAssertionError: If input is a directory, output must be a directory too, got \'stouputils/output.jpg\'
+
+
+\t\t\t> upscale("input.jpg", "output.jpg", 2)
+\t\t\t> # The input.jpg will be upscaled to output.jpg with a ratio of 2
+
+\t\t\t> upscale("input_folder", "output_folder", 2)
+\t\t\t> # The input_folder will be upscaled to output_folder with a ratio of 2
+\t'''
+def upscale_images(images: list[str], output_folder: str, upscale_ratio: int, desc: str = 'Upscaling images') -> None:
+    """ Upscale multiple images from a list.
+
+\tArgs:
+\t\timages        (list[str]): List of paths to the images to upscale.
+\t\toutput_folder (str):       Path to the output folder where the upscaled images will be saved.
+\t\tupscale_ratio (int):       Upscaling ratio.
+\t\tdesc          (str):       Description of the function execution displayed in the progress bar.
+\t\t\tNo progress bar will be displayed if desc is empty.
+
+\tReturns:
+\t\tNone: This function doesn't return anything.
+\t"""
+def upscale_folder(input_folder: str, output_folder: str, upscale_ratio: int, slightly_faster_mode: bool = True, desc: str = 'Upscaling folder') -> None:
+    """ Upscale all images in a folder.
+
+\tArgs:
+\t\tinput_folder          (str):   Path to the input folder containing the images to upscale.
+\t\toutput_folder         (str):   Path to the output folder where the upscaled images will be saved.
+\t\tupscale_ratio         (int):   Upscaling ratio.
+\t\tslightly_faster_mode  (bool):  Whether to use the slightly faster mode (no progress bar),
+\t\t\tone call to the upscaler executable.
+\t\tdesc                  (str):   Description of the function execution displayed in the progress bar.
+\t\t\tNo progress bar will be displayed if desc is empty.
+
+\tReturns:
+\t\tNone: This function doesn't return anything.
+\t"""