Skip to main content

​
Overview

The utils.py module provides essential utility functions for file operations, audio processing, outlier detection, and logging.

​
Functions

​
ffmpeg_exists

​
ffmpeg_exists
function
Checks if FFmpeg is available in the system PATH.Returns: bool - True if FFmpeg is available, False otherwiseExample:
from src.utils import ffmpeg_exists

if not ffmpeg_exists():
    raise RuntimeError("FFmpeg is required but not found")

​
detect_outliers

​
detect_outliers
function
Finds pairwise estimates that disagree strongly with the optimized solution.Parameters:
  • pairwise (Dict[Tuple[str, str], Tuple[float, float]]): Dictionary mapping file pairs to (offset, confidence) tuples
  • optimized (Dict[str, float]): Dictionary mapping filenames to optimized offsets
  • threshold (float): Flag pairs with error > this many seconds (default: 0.5)
Returns: List[Tuple[str, str, float, float, float]] - List of outlier tuples containing:
  • fileA (str): First file name
  • fileB (str): Second file name
  • measured_offset (float): Measured offset in seconds
  • expected_offset (float): Expected offset based on optimization
  • error (float): Absolute difference between measured and expected
Example:
from src.utils import detect_outliers

pairwise = {('cam1.mp4', 'cam2.mp4'): (2.5, 0.8)}
optimized = {'cam1.mp4': 0.0, 'cam2.mp4': 2.3}

outliers = detect_outliers(pairwise, optimized, threshold=0.5)
for fileA, fileB, measured, expected, error in outliers:
    print(f"Outlier: {fileA} <-> {fileB}, error={error:.3f}s")

​
ensure_dir

​
ensure_dir
function
Creates a directory if it doesn’t exist.Parameters:
  • path (str): Directory path to create
Returns: NoneExample:
from src.utils import ensure_dir

ensure_dir("/path/to/output")

​
setup_logger

​
setup_logger
function
Returns a logger with the given name. Configuration is handled centrally in ui.py/main.py.Parameters:
  • name (str): Logger name (default: “sync”)
  • level (int): Logging level (default: logging.INFO)
Returns: logging.Logger - Configured logger instanceExample:
from src.utils import setup_logger
import logging

logger = setup_logger("my_module", level=logging.DEBUG)
logger.info("Processing started")

​
log_execution_time

​
log_execution_time
context manager
Context manager to log the duration of an operation.Parameters:
  • logger (logging.Logger): Logger instance to use
  • operation_name (str): Name of the operation being timed
Example:
from src.utils import log_execution_time, setup_logger

logger = setup_logger()

with log_execution_time(logger, "Video Processing"):
    # Your processing code here
    process_video()
# Logs: "Completed [Video Processing] in 12.34s"

​
next_pow2

​
next_pow2
function
Calculates the next power of 2 greater than or equal to n.Parameters:
  • n (int): Input number
Returns: int - Next power of 2Example:
from src.utils import next_pow2

print(next_pow2(100))  # 128
print(next_pow2(512))  # 512
print(next_pow2(1000)) # 1024

​
load_audio

​
load_audio
function
Loads and normalizes audio from a WAV file.Parameters:
  • path (str): Path to the WAV file
Returns: Tuple[np.ndarray, int] - Tuple containing:
  • data (np.ndarray): Normalized audio data as float32 array (mono)
  • sr (int): Sample rate in Hz
Processing:
  • Converts int16 data to float32 by dividing by 32768.0
  • Converts int32 data to float32 by dividing by 2^31
  • Converts stereo to mono by averaging channels
Example:
from src.utils import load_audio

audio_data, sample_rate = load_audio("audio.wav")
print(f"Sample rate: {sample_rate} Hz")
print(f"Duration: {len(audio_data) / sample_rate:.2f} seconds")

​
Logger

​
logger
logging.Logger
Module-level logger instance for the utils module.
logger = logging.getLogger(__name__)

Build docs developers (and LLMs) love

Get started for freeTalk to us