utils

Time formatting and source info display utilities for review cards

Time Formatting

---

format_time

def format_time(
    seconds:Optional, # Time in seconds
)->str: # Formatted time string (m:ss.s)

Format seconds as m:ss.s for sub-second display.

assert format_time(6.6) == "0:06.6"
assert format_time(9.8) == "0:09.8"
assert format_time(65.25) == "1:05.2"
assert format_time(0.0) == "0:00.0"
assert format_time(None) == "-:--.-"
print("format_time tests passed")

format_time tests passed

---

format_duration

def format_duration(
    start:Optional, # Start time in seconds
    end:Optional, # End time in seconds
)->str: # Formatted duration string (e.g., "3.2s")

Format duration from start/end times.

assert format_duration(6.6, 9.8) == "3.2s"
assert format_duration(0.0, 1.5) == "1.5s"
assert format_duration(None, 9.8) == "-.-s"
assert format_duration(6.6, None) == "-.-s"
print("format_duration tests passed")

format_duration tests passed

Source Info Formatting

---

truncate_id

def truncate_id(
    id_str:Optional, # Full ID string
    length:int=8, # Number of characters to keep
)->str: # Truncated ID with ellipsis if needed

Truncate an ID string for display, adding ellipsis if truncated.

assert truncate_id("job_be1ac4f7d3e2") == "job_be1a..."
assert truncate_id("short") == "short"
assert truncate_id("exactly8") == "exactly8"
assert truncate_id(None) == "-"
assert truncate_id("long_id", length=4) == "long..."
print("truncate_id tests passed")

truncate_id tests passed

---

format_char_range

def format_char_range(
    start_char:Optional, # Start character index
    end_char:Optional, # End character index
)->str: # Formatted range string (e.g., "char:25-68")

Format character range for source reference display.

assert format_char_range(25, 68) == "char:25-68"
assert format_char_range(0, 100) == "char:0-100"
assert format_char_range(None, 68) == "char:-"
assert format_char_range(25, None) == "char:-"
print("format_char_range tests passed")

format_char_range tests passed

---

format_source_info

def format_source_info(
    provider_id:Optional, # Source provider identifier
    source_id:Optional, # Source record ID
    start_char:Optional=None, # Start character index
    end_char:Optional=None, # End character index
)->str: # Formatted source info string

Format source info for display in review cards.

result = format_source_info("voxtral", "job_be1ac4f7d3e2", 25, 68)
assert result == "voxtral | job_be1a... | char:25-68"

result = format_source_info(None, None)
assert result == "- | - | char:-"

result = format_source_info("local", "short", 0, 50)
assert result == "local | short | char:0-50"

print("format_source_info tests passed")

format_source_info tests passed

Document Title

---

generate_document_title

def generate_document_title(
    media_path:Optional, # Path to media file
    default:str='Untitled Document', # Fallback title if path is None
)->str: # Clean document title

Generate a document title from a media file path.

assert generate_document_title("/path/to/my_podcast_episode.mp3") == "My Podcast Episode"
assert generate_document_title("/path/to/audio-file-123.wav") == "Audio File 123"
assert generate_document_title("simple_name.mp3") == "Simple Name"
assert generate_document_title(None) == "Untitled Document"
assert generate_document_title("", "Custom Default") == "Custom Default"
print("generate_document_title tests passed")