# utils


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Time Formatting

------------------------------------------------------------------------

### format_time

``` python

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.*

``` python
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

``` python

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.*

``` python
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

``` python

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.*

``` python
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

``` python

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.*

``` python
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

``` python

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.*

``` python
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

``` python

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.*

``` python
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")
```