| Name | lattifai JSON |
| Version |
0.4.4
JSON |
| download |
| home_page | None |
| Summary | Lattifai Python SDK: Seamless Integration with Lattifai's Speech and Video AI Services |
| upload_time | 2025-11-03 12:36:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.14,>=3.10 |
| license | MIT License
Copyright (c) 2025 Lattifai.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
lattifai
speech recognition
video analysis
ai
sdk
api client
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="https://raw.githubusercontent.com/lattifai/lattifai-python/main/assets/logo.png" width=256>
[](https://badge.fury.io/py/lattifai)
[](https://pypi.org/project/lattifai)
[](https://pepy.tech/project/lattifai)
</div>
<p align="center">
🌐 <a href="https://lattifai.com"><b>Official Website</b></a>    |    🖥️ <a href="https://github.com/lattifai/lattifai-python">GitHub</a>    |    🤗 <a href="https://huggingface.co/Lattifai/Lattice-1-Alpha">Model</a>    |    📑 <a href="https://lattifai.com/blogs">Blog</a>    |    <a href="https://discord.gg/kvF4WsBRK8"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" style="vertical-align: middle;"></a>
</p>
# LattifAI Python
Advanced forced alignment and subtitle generation powered by [Lattice-1-Alpha](https://huggingface.co/Lattifai/Lattice-1-Alpha) model.
## Installation
```bash
pip install install-k2
# The installation will automatically detect and use your already installed PyTorch version(up to 2.8).
install-k2 # Install k2
pip install lattifai
```
> **⚠️ Important**: You must run `install-k2` before using the lattifai library.
```
> install-k2 --help
usage: install-k2 [-h] [--system {linux,darwin,windows}] [--dry-run] [--torch-version TORCH_VERSION]
Auto-install the latest k2 wheel for your environment.
optional arguments:
-h, --help show this help message and exit
--system {linux,darwin,windows}
Override OS detection. Valid values: linux, darwin (macOS), windows. Default: auto-detect
--dry-run Show what would be installed without making changes.
--torch-version TORCH_VERSION
Specify torch version (e.g., 2.8.0). If not specified, will auto-detect or use latest available.
```
## Quick Start
### Command Line
The library provides two equivalent commands: `lai` (recommended for convenience) and `lattifai`.
```bash
# Align audio with subtitle (using lai command)
lai align audio.wav subtitle.srt output.srt
# Or use the full command
lattifai align audio.wav subtitle.srt output.srt
# Download and align YouTube content directly
lai youtube https://www.youtube.com/watch?v=VIDEO_ID
# Process YouTube videos with intelligent workflow (equivalent to lai youtube)
lai agent --youtube https://www.youtube.com/watch?v=VIDEO_ID
# Convert subtitle format
lai subtitle convert input.srt output.vtt
```
> **💡 Tip**: Use `lai` for faster typing in your daily workflow!
#### Command Quick Reference
| Command | Use Case | Best For |
|---------|----------|----------|
| `lai align` | Align existing audio + subtitle files | Local files, custom workflows |
| `lai youtube` | Download & align YouTube content | Quick one-off YouTube processing |
| `lai agent` | Intelligent YouTube workflow with retries | Production, batch jobs, automation |
| `lai subtitle` | Convert subtitle formats | Format conversion only |
#### lai align options
```
> lai align --help
Usage: lattifai align [OPTIONS] INPUT_AUDIO_PATH INPUT_SUBTITLE_PATH OUTPUT_SUBTITLE_PATH
Command used to align audio with subtitles
Options:
-F, --input_format [srt|vtt|ass|ssa|sub|sbv|txt|auto|gemini] Input subtitle format.
-S, --split_sentence Re-segment subtitles by semantics.
-W, --word_level Include word-level alignment timestamps.
-D, --device [cpu|cuda|mps] Device to use for inference.
-M, --model_name_or_path TEXT Model name or path for alignment.
--api_key TEXT API key for LattifAI.
--help Show this message and exit.
```
#### lai youtube command
Download and align YouTube videos in one step. Automatically downloads media, fetches subtitles (or uses Gemini transcription if unavailable), and performs forced alignment.
```bash
# Basic usage
lai youtube https://www.youtube.com/watch?v=VIDEO_ID
# Common options: audio format, sentence splitting, word-level, GPU
lai youtube --media-format mp3 --split-sentence --word-level --device mps \
--output-dir ./output --output-format srt https://www.youtube.com/watch?v=VIDEO_ID
# Use Gemini for transcription fallback
# Gemini API Key: Get yours at https://aistudio.google.com/apikey
# Note: Your API key is completely safe - it's never logged or stored by our codebase
lai youtube --gemini-api-key YOUR_GEMINI_KEY https://www.youtube.com/watch?v=VIDEO_ID
```
**Options**:
```
> lai youtube --help
Usage: lattifai youtube [OPTIONS] YT_URL
Download media and subtitles from YouTube for further alignment.
Options:
-M, --media-format [mp3|wav|m4a|aac|flac|ogg|opus|aiff|mp4|webm|mkv|avi|mov] Media format for YouTube download.
-S, --split-sentence Re-segment subtitles by semantics.
-W, --word-level Include word-level alignment timestamps.
-O, --output-dir PATH Output directory (default: current directory).
-D, --device [cpu|cuda|mps] Device to use for inference.
-M, --model-name-or-path TEXT Model name or path for alignment.
--api-key TEXT API key for LattifAI.
--gemini-api-key TEXT Gemini API key for transcription fallback.
-F, --output-format [srt|vtt|ass|ssa|sub|sbv|txt|json|TextGrid] Subtitle output format.
--help Show this message and exit.
```
#### lai agent command
**Intelligent Agentic Workflow** - Process YouTube videos through an advanced multi-step workflow with automatic retries, smart file management, and comprehensive error handling.
```bash
# Basic usage
lai agent --youtube https://www.youtube.com/watch?v=VIDEO_ID
# Production workflow with retries, verbose logging, and force overwrite
lai agent --youtube --media-format mp4 --output-format TextGrid \
--split-sentence --word-level --device mps --max-retries 2 --verbose --force \
--output-dir ./outputs https://www.youtube.com/watch?v=VIDEO_ID
```
**Key Features**:
- **🔄 Automatic Retry Logic**: Configurable retry mechanism for failed steps
- **📁 Smart File Management**: Detects existing files and prompts for action
- **🎯 Intelligent Workflow**: Multi-step pipeline with dependency management
- **🛡️ Error Recovery**: Graceful handling of failures with detailed logging
- **📊 Rich Output**: Comprehensive results with metadata and file paths
- **⚡ Async Processing**: Efficient parallel execution of independent tasks
**Options**:
```
> lai agent --help
Usage: lattifai agent [OPTIONS] URL
LattifAI Agentic Workflow Agent
Process multimedia content through intelligent agent-based pipelines.
Options:
--youtube, --yt Process YouTube URL through agentic workflow.
--gemini-api-key TEXT Gemini API key for transcription.
--media-format [mp3|wav|m4a|aac|opus|mp4|webm|mkv|...] Media format for YouTube download.
--output-format [srt|vtt|ass|ssa|sub|sbv|txt|json|...] Subtitle output format.
--output-dir PATH Output directory (default: current directory).
--max-retries INTEGER Maximum retries for failed steps.
-S, --split-sentence Re-segment subtitles by semantics.
--word-level Include word-level alignment timestamps.
--verbose, -v Enable verbose logging.
--force, -f Force overwrite without confirmation.
--help Show this message and exit.
```
**When to use `lai agent` vs `lai youtube`**:
- Both `lai agent --youtube URL` and `lai youtube URL` provide the same core functionality for downloading and aligning YouTube content
- **Use `lai agent --youtube`**: For production workflows, batch processing, advanced error handling, and when you need retry logic
- **Use `lai youtube`**: For quick one-off downloads and alignment with minimal overhead
#### Understanding --split_sentence
The `--split_sentence` option performs intelligent sentence re-splitting based on punctuation and semantic boundaries. This is especially useful when processing subtitles that combine multiple semantic units in a single segment, such as:
- **Mixed content**: Non-speech elements (e.g., `[APPLAUSE]`, `[MUSIC]`) followed by actual dialogue
- **Natural punctuation boundaries**: Colons, periods, and other punctuation marks that indicate semantic breaks
- **Concatenated phrases**: Multiple distinct utterances joined together without proper separation
**Example transformations**:
```
Input: "[APPLAUSE] >> MIRA MURATI: Thank you all"
Output: ["[APPLAUSE]", ">> MIRA MURATI: Thank you all"]
Input: "[MUSIC] Welcome back. Today we discuss AI."
Output: ["[MUSIC]", "Welcome back.", "Today we discuss AI."]
```
This feature helps improve alignment accuracy by:
1. Respecting punctuation-based semantic boundaries
2. Separating distinct utterances for more precise timing
3. Maintaining semantic context for each independent phrase
**Usage**:
```bash
lai align --split_sentence audio.wav subtitle.srt output.srt
```
#### Understanding --word_level
The `--word_level` option enables word-level alignment, providing precise timing information for each individual word in the audio. When enabled, the output includes detailed word boundaries within each subtitle segment, allowing for fine-grained synchronization and analysis.
**Key features**:
- **Individual word timestamps**: Each word gets its own start and end time
- **Format-specific output**:
- **JSON (Recommended)**: Full alignment details stored in `alignment.word` field of each segment, preserving all word-level timing information in a structured format
- **TextGrid**: Separate "words" tier alongside the "utterances" tier for linguistic analysis
- **TXT**: Each word on a separate line with timestamp range: `[start-end] word`
- **Standard subtitle formats** (SRT, VTT, ASS, etc.): Each word becomes a separate subtitle event
> **💡 Recommended**: Use JSON format (`output.json`) to preserve complete word-level alignment data. Other formats may lose some structural information.
**Example output formats**:
**JSON format** (with word-level details):
```json
[
{
"id": "6",
"recording_id": "",
"start": 24.52,
"duration": 9.1,
"channel": 0,
"text": "We will start with why it is so important to us to have a product that we can make truly available and broadly available to everyone.",
"custom": {
"score": 0.8754
},
"alignment": {
"word": [
[
"We",
24.6,
0.14,
1.0
],
[
"will",
24.74,
0.14,
1.0
],
[
"start",
24.88,
0.46,
0.771
],
[
"with",
25.34,
0.28,
0.9538
],
[
"why",
26.2,
0.36,
1.0
],
[
"it",
26.56,
0.14,
0.9726
],
[
"is",
26.74,
0.02,
0.6245
],
[
"so",
26.76,
0.16,
0.6615
],
[
"important",
26.92,
0.54,
0.9257
],
[
"to",
27.5,
0.1,
1.0
],
[
"us",
27.6,
0.34,
0.7955
],
[
"to",
28.04,
0.08,
0.8545
],
[
"have",
28.16,
0.46,
0.9994
],
[
"a",
28.76,
0.06,
1.0
],
[
"product",
28.82,
0.56,
0.9975
],
[
"that",
29.38,
0.08,
0.5602
],
[
"we",
29.46,
0.16,
0.7017
],
[
"can",
29.62,
0.22,
1.0
],
[
"make",
29.84,
0.32,
0.9643
],
[
"truly",
30.42,
0.32,
0.6737
],
[
"available",
30.74,
0.6,
0.9349
],
[
"and",
31.4,
0.2,
0.4114
],
[
"broadly",
31.6,
0.44,
0.6726
],
[
"available",
32.04,
0.58,
0.9108
],
[
"to",
32.72,
0.06,
1.0
],
[
"everyone.",
32.78,
0.64,
0.7886
]
]
}
}
]
```
**TXT format** (word-level):
```
[0.50-1.20] Hello
[1.20-2.30] world
```
**TextGrid format** (Praat-compatible):
```
Two tiers created:
- "utterances" tier: Full segments with original text
- "words" tier: Individual words with precise boundaries
```
**Use cases**:
- **Linguistic analysis**: Study pronunciation patterns, speech timing, and prosody
- **Accessibility**: Create more granular captions for hearing-impaired users
- **Video/Audio editing**: Enable precise word-level subtitle synchronization
- **Karaoke applications**: Highlight individual words as they are spoken
- **Language learning**: Provide precise word boundaries for pronunciation practice
**Usage**:
```bash
# Generate word-level aligned JSON
lai align --word_level audio.wav subtitle.srt output.json
# Create TextGrid file for Praat analysis
lai align --word_level audio.wav subtitle.srt output.TextGrid
# Word-level TXT output
lai align --word_level audio.wav subtitle.srt output.txt
# Standard subtitle with word-level events
lai align --word_level audio.wav subtitle.srt output.srt
```
**Combined with --split_sentence**:
```bash
# Optimal alignment: semantic splitting + word-level details
lai align --split_sentence --word_level audio.wav subtitle.srt output.json
```
### Python API
```python
from lattifai import LattifAI
client = LattifAI() # api_key will be read from LATTIFAI_API_KEY if not provided
alignments, output_path = client.alignment(
audio="audio.wav",
subtitle="subtitle.srt",
output_subtitle_path="output.srt",
)
```
Need to run inside an async application? Use the drop-in asynchronous client:
```python
import asyncio
from lattifai import AsyncLattifAI
async def main():
async with AsyncLattifAI() as client:
alignments, output_path = await client.alignment(
audio="audio.wav",
subtitle="subtitle.srt",
split_sentence=False,
output_subtitle_path="output.srt",
)
asyncio.run(main())
```
Both clients return a list of `Supervision` segments with timing information and, if provided, the path where the aligned subtitle was written.
## Supported Formats
**Audio**: WAV, MP3, M4A, AAC, FLAC, OGG, OPUS, AIFF
**Video**: MP4, MKV, MOV, WEBM, AVI
**Subtitle Input**: SRT, VTT, ASS, SSA, SUB, SBV, TXT (plain text), Gemini (Google Gemini transcript format)
**Subtitle Output**: All input formats plus TextGrid (Praat format for linguistic analysis)
## API Reference
### LattifAI (sync)
```python
LattifAI(
api_key: Optional[str] = None,
model_name_or_path: str = 'Lattifai/Lattice-1-Alpha',
device: str = 'cpu', # 'cpu', 'cuda', or 'mps'
)
```
### AsyncLattifAI (async)
```python
AsyncLattifAI(
api_key: Optional[str] = None,
model_name_or_path: str = 'Lattifai/Lattice-1-Alpha',
device: str = 'cpu',
)
```
Use `async with AsyncLattifAI() as client:` or call `await client.close()` when you are done to release the underlying HTTP session.
### alignment()
```python
client.alignment(
audio: str, # Path to audio file
subtitle: str, # Path to subtitle/text file
format: Optional[str] = None, # Input format: 'srt', 'vtt', 'ass', 'txt', 'gemini', or 'auto' (auto-detect if None)
split_sentence: bool = False, # Smart sentence splitting based on punctuation semantics
return_details: bool = False, # Enable word-level alignment details
output_subtitle_path: Optional[str] = None
) -> Tuple[List[Supervision], Optional[str]] # await client.alignment(...) for AsyncLattifAI
```
**Parameters**:
- `audio`: Path to the audio file to be aligned
- `subtitle`: Path to the subtitle or text file
- `format`: Input subtitle format. Supported values: 'srt', 'vtt', 'ass', 'txt', 'gemini', 'auto'. When set to None or 'auto', the format is automatically detected from file extension. Additional formats (ssa, sub, sbv) are supported through automatic format detection
- `split_sentence`: Enable intelligent sentence re-splitting (default: False). Set to True when subtitles combine multiple semantic units (non-speech elements + dialogue, or multiple sentences) that would benefit from separate timing alignment
- `return_details`: Enable word-level alignment details (default: False). When True, each `Supervision` object includes an `alignment` field with word-level timestamps, accessible via `supervision.alignment['word']`. This provides precise timing for each individual word within the segment
- `output_subtitle_path`: Output path for aligned subtitle (optional)
**Returns**:
- A tuple containing:
- `alignments`: List of aligned `Supervision` objects with timing information
- `output_subtitle_path`: Path where the subtitle was written (if `output_subtitle_path` was provided)
## Examples
### Basic Text Alignment
```python
from lattifai import LattifAI
client = LattifAI()
alignments, output_path = client.alignment(
audio="speech.wav",
subtitle="transcript.txt",
format="txt",
split_sentence=False,
output_subtitle_path="output.srt"
)
```
### Word-Level Alignment
```python
from lattifai import LattifAI
client = LattifAI()
alignments, output_path = client.alignment(
audio="speech.wav",
subtitle="transcript.srt",
return_details=True, # Enable word-level alignment
output_subtitle_path="output.json" # JSON format preserves word-level data
)
# Access word-level timestamps
for segment in alignments:
print(f"Segment: {segment.text} ({segment.start:.2f}s - {segment.end:.2f}s)")
if segment.alignment and 'word' in segment.alignment:
for word in segment.alignment['word']:
print(f" Word: {word.symbol} ({word.start:.2f}s - {word.end:.2f}s)")
```
### Batch Processing
```python
from pathlib import Path
from lattifai import LattifAI
client = LattifAI()
audio_dir = Path("audio_files")
subtitle_dir = Path("subtitles")
output_dir = Path("aligned")
for audio in audio_dir.glob("*.wav"):
subtitle = subtitle_dir / f"{audio.stem}.srt"
if subtitle.exists():
alignments, output_path = client.alignment(
audio=audio,
subtitle=subtitle,
output_subtitle_path=output_dir / f"{audio.stem}_aligned.srt"
)
```
### GPU Acceleration
```python
from lattifai import LattifAI
# NVIDIA GPU
client = LattifAI(device='cuda')
# Apple Silicon
client = LattifAI(device='mps')
# CLI
lai align --device mps audio.wav subtitle.srt output.srt
```
### YouTube Processing with Agent Workflow
```python
import asyncio
from lattifai.workflows import YouTubeSubtitleAgent
async def process_youtube():
# Initialize agent with configuration
agent = YouTubeSubtitleAgent(
gemini_api_key="your-gemini-api-key",
video_format="mp4", # or "mp3", "wav", etc.
output_format="srt",
max_retries=2,
split_sentence=True,
word_level=True,
force_overwrite=False
)
# Process YouTube URL
result = await agent.process_youtube_url(
url="https://www.youtube.com/watch?v=VIDEO_ID",
output_dir="./output",
output_format="srt"
)
# Access results
print(f"Title: {result['metadata']['title']}")
print(f"Duration: {result['metadata']['duration']} seconds")
print(f"Subtitle count: {result['subtitle_count']}")
# Access generated files
for format_name, file_path in result['exported_files'].items():
print(f"{format_name.upper()}: {file_path}")
# Run the async workflow
asyncio.run(process_youtube())
```
## Configuration
### API Key Setup
First, create your API key at [https://lattifai.com/dashboard/api-keys](https://lattifai.com/dashboard/api-keys)
**Recommended: Using .env file**
Create a `.env` file in your project root:
```bash
LATTIFAI_API_KEY=your-api-key
```
The library automatically loads the `.env` file (python-dotenv is included as a dependency).
**Alternative: Environment variable**
```bash
export LATTIFAI_API_KEY="your-api-key"
```
## Model Information
**[Lattice-1-Alpha](https://huggingface.co/Lattifai/Lattice-1-Alpha)** features:
- State-of-the-art alignment precision
- **Language Support**: Currently supports English only. The upcoming **Lattice-1** release will support English, Chinese, and mixed English-Chinese content.
- Handles noisy audio and imperfect transcripts
- Optimized for CPU and GPU (CUDA/MPS)
**Requirements**:
- Python 3.10 - 3.13 (3.14 support coming soon)
- 4GB RAM recommended
- ~2GB storage for model files
## Development
### Setup
```bash
git clone https://github.com/lattifai/lattifai-python.git
cd lattifai-python
pip install -e ".[test]"
./scripts/install-hooks.sh # Optional: install pre-commit hooks
```
### Testing
```bash
pytest # Run all tests
pytest --cov=src # With coverage
pytest tests/test_basic.py # Specific test
```
### Code Quality
```bash
ruff check src/ tests/ # Lint
ruff format src/ tests/ # Format
isort src/ tests/ # Sort imports
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes and add tests
4. Run `pytest` and `ruff check`
5. Submit a pull request
## License
Apache License 2.0
## Support
- **Issues**: [GitHub Issues](https://github.com/lattifai/lattifai-python/issues)
- **Discussions**: [GitHub Discussions](https://github.com/lattifai/lattifai-python/discussions)
- **Discord**: [Join our community](https://discord.gg/kvF4WsBRK8)
Raw data
{
"_id": null,
"home_page": null,
"name": "lattifai",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": "Lattice <tech@lattifai.com>",
"keywords": "lattifai, speech recognition, video analysis, ai, sdk, api client",
"author": null,
"author_email": "Lattifai Technologies <tech@lattifai.com>",
"download_url": null,
"platform": null,
"description": "<div align=\"center\">\n<img src=\"https://raw.githubusercontent.com/lattifai/lattifai-python/main/assets/logo.png\" width=256>\n\n[](https://badge.fury.io/py/lattifai)\n[](https://pypi.org/project/lattifai)\n[](https://pepy.tech/project/lattifai)\n</div>\n\n<p align=\"center\">\n \ud83c\udf10 <a href=\"https://lattifai.com\"><b>Official Website</b></a>    |    \ud83d\udda5\ufe0f <a href=\"https://github.com/lattifai/lattifai-python\">GitHub</a>    |    \ud83e\udd17 <a href=\"https://huggingface.co/Lattifai/Lattice-1-Alpha\">Model</a>    |    \ud83d\udcd1 <a href=\"https://lattifai.com/blogs\">Blog</a>    |    <a href=\"https://discord.gg/kvF4WsBRK8\"><img src=\"https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white\" alt=\"Discord\" style=\"vertical-align: middle;\"></a>\n</p>\n\n\n# LattifAI Python\n\nAdvanced forced alignment and subtitle generation powered by [Lattice-1-Alpha](https://huggingface.co/Lattifai/Lattice-1-Alpha) model.\n\n## Installation\n\n```bash\npip install install-k2\n# The installation will automatically detect and use your already installed PyTorch version(up to 2.8).\ninstall-k2 # Install k2\n\npip install lattifai\n```\n> **\u26a0\ufe0f Important**: You must run `install-k2` before using the lattifai library.\n```\n> install-k2 --help\nusage: install-k2 [-h] [--system {linux,darwin,windows}] [--dry-run] [--torch-version TORCH_VERSION]\n\nAuto-install the latest k2 wheel for your environment.\n\noptional arguments:\n -h, --help show this help message and exit\n --system {linux,darwin,windows}\n Override OS detection. Valid values: linux, darwin (macOS), windows. Default: auto-detect\n --dry-run Show what would be installed without making changes.\n --torch-version TORCH_VERSION\n Specify torch version (e.g., 2.8.0). If not specified, will auto-detect or use latest available.\n```\n\n\n## Quick Start\n\n### Command Line\n\nThe library provides two equivalent commands: `lai` (recommended for convenience) and `lattifai`.\n\n```bash\n# Align audio with subtitle (using lai command)\nlai align audio.wav subtitle.srt output.srt\n# Or use the full command\nlattifai align audio.wav subtitle.srt output.srt\n\n# Download and align YouTube content directly\nlai youtube https://www.youtube.com/watch?v=VIDEO_ID\n\n# Process YouTube videos with intelligent workflow (equivalent to lai youtube)\nlai agent --youtube https://www.youtube.com/watch?v=VIDEO_ID\n\n# Convert subtitle format\nlai subtitle convert input.srt output.vtt\n```\n\n> **\ud83d\udca1 Tip**: Use `lai` for faster typing in your daily workflow!\n\n#### Command Quick Reference\n\n| Command | Use Case | Best For |\n|---------|----------|----------|\n| `lai align` | Align existing audio + subtitle files | Local files, custom workflows |\n| `lai youtube` | Download & align YouTube content | Quick one-off YouTube processing |\n| `lai agent` | Intelligent YouTube workflow with retries | Production, batch jobs, automation |\n| `lai subtitle` | Convert subtitle formats | Format conversion only |\n\n#### lai align options\n```\n> lai align --help\nUsage: lattifai align [OPTIONS] INPUT_AUDIO_PATH INPUT_SUBTITLE_PATH OUTPUT_SUBTITLE_PATH\n\n Command used to align audio with subtitles\n\nOptions:\n -F, --input_format [srt|vtt|ass|ssa|sub|sbv|txt|auto|gemini] Input subtitle format.\n -S, --split_sentence Re-segment subtitles by semantics.\n -W, --word_level Include word-level alignment timestamps.\n -D, --device [cpu|cuda|mps] Device to use for inference.\n -M, --model_name_or_path TEXT Model name or path for alignment.\n --api_key TEXT API key for LattifAI.\n --help Show this message and exit.\n```\n\n#### lai youtube command\n\nDownload and align YouTube videos in one step. Automatically downloads media, fetches subtitles (or uses Gemini transcription if unavailable), and performs forced alignment.\n\n```bash\n# Basic usage\nlai youtube https://www.youtube.com/watch?v=VIDEO_ID\n\n# Common options: audio format, sentence splitting, word-level, GPU\nlai youtube --media-format mp3 --split-sentence --word-level --device mps \\\n --output-dir ./output --output-format srt https://www.youtube.com/watch?v=VIDEO_ID\n\n# Use Gemini for transcription fallback\n# Gemini API Key: Get yours at https://aistudio.google.com/apikey\n# Note: Your API key is completely safe - it's never logged or stored by our codebase\nlai youtube --gemini-api-key YOUR_GEMINI_KEY https://www.youtube.com/watch?v=VIDEO_ID\n```\n\n**Options**:\n```\n> lai youtube --help\nUsage: lattifai youtube [OPTIONS] YT_URL\n\n Download media and subtitles from YouTube for further alignment.\n\nOptions:\n -M, --media-format [mp3|wav|m4a|aac|flac|ogg|opus|aiff|mp4|webm|mkv|avi|mov] Media format for YouTube download.\n -S, --split-sentence Re-segment subtitles by semantics.\n -W, --word-level Include word-level alignment timestamps.\n -O, --output-dir PATH Output directory (default: current directory).\n -D, --device [cpu|cuda|mps] Device to use for inference.\n -M, --model-name-or-path TEXT Model name or path for alignment.\n --api-key TEXT API key for LattifAI.\n --gemini-api-key TEXT Gemini API key for transcription fallback.\n -F, --output-format [srt|vtt|ass|ssa|sub|sbv|txt|json|TextGrid] Subtitle output format.\n --help Show this message and exit.\n```\n\n#### lai agent command\n\n**Intelligent Agentic Workflow** - Process YouTube videos through an advanced multi-step workflow with automatic retries, smart file management, and comprehensive error handling.\n\n```bash\n# Basic usage\nlai agent --youtube https://www.youtube.com/watch?v=VIDEO_ID\n\n# Production workflow with retries, verbose logging, and force overwrite\nlai agent --youtube --media-format mp4 --output-format TextGrid \\\n --split-sentence --word-level --device mps --max-retries 2 --verbose --force \\\n --output-dir ./outputs https://www.youtube.com/watch?v=VIDEO_ID\n```\n\n**Key Features**:\n- **\ud83d\udd04 Automatic Retry Logic**: Configurable retry mechanism for failed steps\n- **\ud83d\udcc1 Smart File Management**: Detects existing files and prompts for action\n- **\ud83c\udfaf Intelligent Workflow**: Multi-step pipeline with dependency management\n- **\ud83d\udee1\ufe0f Error Recovery**: Graceful handling of failures with detailed logging\n- **\ud83d\udcca Rich Output**: Comprehensive results with metadata and file paths\n- **\u26a1 Async Processing**: Efficient parallel execution of independent tasks\n\n**Options**:\n```\n> lai agent --help\nUsage: lattifai agent [OPTIONS] URL\n\n LattifAI Agentic Workflow Agent\n\n Process multimedia content through intelligent agent-based pipelines.\n\nOptions:\n --youtube, --yt Process YouTube URL through agentic workflow.\n --gemini-api-key TEXT Gemini API key for transcription.\n --media-format [mp3|wav|m4a|aac|opus|mp4|webm|mkv|...] Media format for YouTube download.\n --output-format [srt|vtt|ass|ssa|sub|sbv|txt|json|...] Subtitle output format.\n --output-dir PATH Output directory (default: current directory).\n --max-retries INTEGER Maximum retries for failed steps.\n -S, --split-sentence Re-segment subtitles by semantics.\n --word-level Include word-level alignment timestamps.\n --verbose, -v Enable verbose logging.\n --force, -f Force overwrite without confirmation.\n --help Show this message and exit.\n```\n\n**When to use `lai agent` vs `lai youtube`**:\n- Both `lai agent --youtube URL` and `lai youtube URL` provide the same core functionality for downloading and aligning YouTube content\n- **Use `lai agent --youtube`**: For production workflows, batch processing, advanced error handling, and when you need retry logic\n- **Use `lai youtube`**: For quick one-off downloads and alignment with minimal overhead\n\n#### Understanding --split_sentence\n\nThe `--split_sentence` option performs intelligent sentence re-splitting based on punctuation and semantic boundaries. This is especially useful when processing subtitles that combine multiple semantic units in a single segment, such as:\n\n- **Mixed content**: Non-speech elements (e.g., `[APPLAUSE]`, `[MUSIC]`) followed by actual dialogue\n- **Natural punctuation boundaries**: Colons, periods, and other punctuation marks that indicate semantic breaks\n- **Concatenated phrases**: Multiple distinct utterances joined together without proper separation\n\n**Example transformations**:\n```\nInput: \"[APPLAUSE] >> MIRA MURATI: Thank you all\"\nOutput: [\"[APPLAUSE]\", \">> MIRA MURATI: Thank you all\"]\n\nInput: \"[MUSIC] Welcome back. Today we discuss AI.\"\nOutput: [\"[MUSIC]\", \"Welcome back.\", \"Today we discuss AI.\"]\n```\n\nThis feature helps improve alignment accuracy by:\n1. Respecting punctuation-based semantic boundaries\n2. Separating distinct utterances for more precise timing\n3. Maintaining semantic context for each independent phrase\n\n**Usage**:\n```bash\nlai align --split_sentence audio.wav subtitle.srt output.srt\n```\n\n#### Understanding --word_level\n\nThe `--word_level` option enables word-level alignment, providing precise timing information for each individual word in the audio. When enabled, the output includes detailed word boundaries within each subtitle segment, allowing for fine-grained synchronization and analysis.\n\n**Key features**:\n- **Individual word timestamps**: Each word gets its own start and end time\n- **Format-specific output**:\n - **JSON (Recommended)**: Full alignment details stored in `alignment.word` field of each segment, preserving all word-level timing information in a structured format\n - **TextGrid**: Separate \"words\" tier alongside the \"utterances\" tier for linguistic analysis\n - **TXT**: Each word on a separate line with timestamp range: `[start-end] word`\n - **Standard subtitle formats** (SRT, VTT, ASS, etc.): Each word becomes a separate subtitle event\n\n> **\ud83d\udca1 Recommended**: Use JSON format (`output.json`) to preserve complete word-level alignment data. Other formats may lose some structural information.\n\n**Example output formats**:\n\n**JSON format** (with word-level details):\n```json\n[\n{\n \"id\": \"6\",\n \"recording_id\": \"\",\n \"start\": 24.52,\n \"duration\": 9.1,\n \"channel\": 0,\n \"text\": \"We will start with why it is so important to us to have a product that we can make truly available and broadly available to everyone.\",\n \"custom\": {\n \"score\": 0.8754\n },\n \"alignment\": {\n \"word\": [\n [\n \"We\",\n 24.6,\n 0.14,\n 1.0\n ],\n [\n \"will\",\n 24.74,\n 0.14,\n 1.0\n ],\n [\n \"start\",\n 24.88,\n 0.46,\n 0.771\n ],\n [\n \"with\",\n 25.34,\n 0.28,\n 0.9538\n ],\n [\n \"why\",\n 26.2,\n 0.36,\n 1.0\n ],\n [\n \"it\",\n 26.56,\n 0.14,\n 0.9726\n ],\n [\n \"is\",\n 26.74,\n 0.02,\n 0.6245\n ],\n [\n \"so\",\n 26.76,\n 0.16,\n 0.6615\n ],\n [\n \"important\",\n 26.92,\n 0.54,\n 0.9257\n ],\n [\n \"to\",\n 27.5,\n 0.1,\n 1.0\n ],\n [\n \"us\",\n 27.6,\n 0.34,\n 0.7955\n ],\n [\n \"to\",\n 28.04,\n 0.08,\n 0.8545\n ],\n [\n \"have\",\n 28.16,\n 0.46,\n 0.9994\n ],\n [\n \"a\",\n 28.76,\n 0.06,\n 1.0\n ],\n [\n \"product\",\n 28.82,\n 0.56,\n 0.9975\n ],\n [\n \"that\",\n 29.38,\n 0.08,\n 0.5602\n ],\n [\n \"we\",\n 29.46,\n 0.16,\n 0.7017\n ],\n [\n \"can\",\n 29.62,\n 0.22,\n 1.0\n ],\n [\n \"make\",\n 29.84,\n 0.32,\n 0.9643\n ],\n [\n \"truly\",\n 30.42,\n 0.32,\n 0.6737\n ],\n [\n \"available\",\n 30.74,\n 0.6,\n 0.9349\n ],\n [\n \"and\",\n 31.4,\n 0.2,\n 0.4114\n ],\n [\n \"broadly\",\n 31.6,\n 0.44,\n 0.6726\n ],\n [\n \"available\",\n 32.04,\n 0.58,\n 0.9108\n ],\n [\n \"to\",\n 32.72,\n 0.06,\n 1.0\n ],\n [\n \"everyone.\",\n 32.78,\n 0.64,\n 0.7886\n ]\n ]\n }\n}\n]\n```\n\n**TXT format** (word-level):\n```\n[0.50-1.20] Hello\n[1.20-2.30] world\n```\n\n**TextGrid format** (Praat-compatible):\n```\nTwo tiers created:\n- \"utterances\" tier: Full segments with original text\n- \"words\" tier: Individual words with precise boundaries\n```\n\n**Use cases**:\n- **Linguistic analysis**: Study pronunciation patterns, speech timing, and prosody\n- **Accessibility**: Create more granular captions for hearing-impaired users\n- **Video/Audio editing**: Enable precise word-level subtitle synchronization\n- **Karaoke applications**: Highlight individual words as they are spoken\n- **Language learning**: Provide precise word boundaries for pronunciation practice\n\n**Usage**:\n```bash\n# Generate word-level aligned JSON\nlai align --word_level audio.wav subtitle.srt output.json\n\n# Create TextGrid file for Praat analysis\nlai align --word_level audio.wav subtitle.srt output.TextGrid\n\n# Word-level TXT output\nlai align --word_level audio.wav subtitle.srt output.txt\n\n# Standard subtitle with word-level events\nlai align --word_level audio.wav subtitle.srt output.srt\n```\n\n**Combined with --split_sentence**:\n```bash\n# Optimal alignment: semantic splitting + word-level details\nlai align --split_sentence --word_level audio.wav subtitle.srt output.json\n```\n\n### Python API\n\n```python\nfrom lattifai import LattifAI\n\nclient = LattifAI() # api_key will be read from LATTIFAI_API_KEY if not provided\nalignments, output_path = client.alignment(\n audio=\"audio.wav\",\n subtitle=\"subtitle.srt\",\n output_subtitle_path=\"output.srt\",\n)\n```\n\nNeed to run inside an async application? Use the drop-in asynchronous client:\n\n```python\nimport asyncio\nfrom lattifai import AsyncLattifAI\n\n\nasync def main():\n async with AsyncLattifAI() as client:\n alignments, output_path = await client.alignment(\n audio=\"audio.wav\",\n subtitle=\"subtitle.srt\",\n split_sentence=False,\n output_subtitle_path=\"output.srt\",\n )\n\n\nasyncio.run(main())\n```\n\nBoth clients return a list of `Supervision` segments with timing information and, if provided, the path where the aligned subtitle was written.\n\n## Supported Formats\n\n**Audio**: WAV, MP3, M4A, AAC, FLAC, OGG, OPUS, AIFF\n\n**Video**: MP4, MKV, MOV, WEBM, AVI\n\n**Subtitle Input**: SRT, VTT, ASS, SSA, SUB, SBV, TXT (plain text), Gemini (Google Gemini transcript format)\n\n**Subtitle Output**: All input formats plus TextGrid (Praat format for linguistic analysis)\n\n## API Reference\n\n### LattifAI (sync)\n\n```python\nLattifAI(\n api_key: Optional[str] = None,\n model_name_or_path: str = 'Lattifai/Lattice-1-Alpha',\n device: str = 'cpu', # 'cpu', 'cuda', or 'mps'\n)\n```\n\n### AsyncLattifAI (async)\n\n```python\nAsyncLattifAI(\n api_key: Optional[str] = None,\n model_name_or_path: str = 'Lattifai/Lattice-1-Alpha',\n device: str = 'cpu',\n)\n```\n\nUse `async with AsyncLattifAI() as client:` or call `await client.close()` when you are done to release the underlying HTTP session.\n\n### alignment()\n\n```python\nclient.alignment(\n audio: str, # Path to audio file\n subtitle: str, # Path to subtitle/text file\n format: Optional[str] = None, # Input format: 'srt', 'vtt', 'ass', 'txt', 'gemini', or 'auto' (auto-detect if None)\n split_sentence: bool = False, # Smart sentence splitting based on punctuation semantics\n return_details: bool = False, # Enable word-level alignment details\n output_subtitle_path: Optional[str] = None\n) -> Tuple[List[Supervision], Optional[str]] # await client.alignment(...) for AsyncLattifAI\n```\n\n**Parameters**:\n- `audio`: Path to the audio file to be aligned\n- `subtitle`: Path to the subtitle or text file\n- `format`: Input subtitle format. Supported values: 'srt', 'vtt', 'ass', 'txt', 'gemini', 'auto'. When set to None or 'auto', the format is automatically detected from file extension. Additional formats (ssa, sub, sbv) are supported through automatic format detection\n- `split_sentence`: Enable intelligent sentence re-splitting (default: False). Set to True when subtitles combine multiple semantic units (non-speech elements + dialogue, or multiple sentences) that would benefit from separate timing alignment\n- `return_details`: Enable word-level alignment details (default: False). When True, each `Supervision` object includes an `alignment` field with word-level timestamps, accessible via `supervision.alignment['word']`. This provides precise timing for each individual word within the segment\n- `output_subtitle_path`: Output path for aligned subtitle (optional)\n\n**Returns**:\n- A tuple containing:\n - `alignments`: List of aligned `Supervision` objects with timing information\n - `output_subtitle_path`: Path where the subtitle was written (if `output_subtitle_path` was provided)\n\n## Examples\n\n### Basic Text Alignment\n\n```python\nfrom lattifai import LattifAI\n\nclient = LattifAI()\nalignments, output_path = client.alignment(\n audio=\"speech.wav\",\n subtitle=\"transcript.txt\",\n format=\"txt\",\n split_sentence=False,\n output_subtitle_path=\"output.srt\"\n)\n```\n\n### Word-Level Alignment\n\n```python\nfrom lattifai import LattifAI\n\nclient = LattifAI()\nalignments, output_path = client.alignment(\n audio=\"speech.wav\",\n subtitle=\"transcript.srt\",\n return_details=True, # Enable word-level alignment\n output_subtitle_path=\"output.json\" # JSON format preserves word-level data\n)\n\n# Access word-level timestamps\nfor segment in alignments:\n print(f\"Segment: {segment.text} ({segment.start:.2f}s - {segment.end:.2f}s)\")\n if segment.alignment and 'word' in segment.alignment:\n for word in segment.alignment['word']:\n print(f\" Word: {word.symbol} ({word.start:.2f}s - {word.end:.2f}s)\")\n```\n\n### Batch Processing\n\n```python\nfrom pathlib import Path\nfrom lattifai import LattifAI\n\nclient = LattifAI()\naudio_dir = Path(\"audio_files\")\nsubtitle_dir = Path(\"subtitles\")\noutput_dir = Path(\"aligned\")\n\nfor audio in audio_dir.glob(\"*.wav\"):\n subtitle = subtitle_dir / f\"{audio.stem}.srt\"\n if subtitle.exists():\n alignments, output_path = client.alignment(\n audio=audio,\n subtitle=subtitle,\n output_subtitle_path=output_dir / f\"{audio.stem}_aligned.srt\"\n )\n```\n\n### GPU Acceleration\n\n```python\nfrom lattifai import LattifAI\n\n# NVIDIA GPU\nclient = LattifAI(device='cuda')\n\n# Apple Silicon\nclient = LattifAI(device='mps')\n\n# CLI\nlai align --device mps audio.wav subtitle.srt output.srt\n```\n\n### YouTube Processing with Agent Workflow\n\n```python\nimport asyncio\nfrom lattifai.workflows import YouTubeSubtitleAgent\n\nasync def process_youtube():\n # Initialize agent with configuration\n agent = YouTubeSubtitleAgent(\n gemini_api_key=\"your-gemini-api-key\",\n video_format=\"mp4\", # or \"mp3\", \"wav\", etc.\n output_format=\"srt\",\n max_retries=2,\n split_sentence=True,\n word_level=True,\n force_overwrite=False\n )\n\n # Process YouTube URL\n result = await agent.process_youtube_url(\n url=\"https://www.youtube.com/watch?v=VIDEO_ID\",\n output_dir=\"./output\",\n output_format=\"srt\"\n )\n\n # Access results\n print(f\"Title: {result['metadata']['title']}\")\n print(f\"Duration: {result['metadata']['duration']} seconds\")\n print(f\"Subtitle count: {result['subtitle_count']}\")\n\n # Access generated files\n for format_name, file_path in result['exported_files'].items():\n print(f\"{format_name.upper()}: {file_path}\")\n\n# Run the async workflow\nasyncio.run(process_youtube())\n```\n\n## Configuration\n\n### API Key Setup\n\nFirst, create your API key at [https://lattifai.com/dashboard/api-keys](https://lattifai.com/dashboard/api-keys)\n\n**Recommended: Using .env file**\n\nCreate a `.env` file in your project root:\n```bash\nLATTIFAI_API_KEY=your-api-key\n```\n\nThe library automatically loads the `.env` file (python-dotenv is included as a dependency).\n\n**Alternative: Environment variable**\n```bash\nexport LATTIFAI_API_KEY=\"your-api-key\"\n```\n\n## Model Information\n\n**[Lattice-1-Alpha](https://huggingface.co/Lattifai/Lattice-1-Alpha)** features:\n- State-of-the-art alignment precision\n- **Language Support**: Currently supports English only. The upcoming **Lattice-1** release will support English, Chinese, and mixed English-Chinese content.\n- Handles noisy audio and imperfect transcripts\n- Optimized for CPU and GPU (CUDA/MPS)\n\n**Requirements**:\n- Python 3.10 - 3.13 (3.14 support coming soon)\n- 4GB RAM recommended\n- ~2GB storage for model files\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/lattifai/lattifai-python.git\ncd lattifai-python\npip install -e \".[test]\"\n./scripts/install-hooks.sh # Optional: install pre-commit hooks\n```\n\n### Testing\n\n```bash\npytest # Run all tests\npytest --cov=src # With coverage\npytest tests/test_basic.py # Specific test\n```\n\n### Code Quality\n\n```bash\nruff check src/ tests/ # Lint\nruff format src/ tests/ # Format\nisort src/ tests/ # Sort imports\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes and add tests\n4. Run `pytest` and `ruff check`\n5. Submit a pull request\n\n## License\n\nApache License 2.0\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/lattifai/lattifai-python/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/lattifai/lattifai-python/discussions)\n- **Discord**: [Join our community](https://discord.gg/kvF4WsBRK8)\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Lattifai.\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Lattifai Python SDK: Seamless Integration with Lattifai's Speech and Video AI Services",
"version": "0.4.4",
"project_urls": {
"Bug Tracker": "https://github.com/lattifai/lattifai-python/issues",
"Changelog": "https://github.com/lattifai/lattifai-python/CHANGELOG.md",
"Discussions": "https://github.com/lattifai/lattifai-python/discussions",
"Documentation": "https://github.com/lattifai/lattifai-python/README.md",
"Homepage": "https://github.com/lattifai/lattifai-python"
},
"split_keywords": [
"lattifai",
" speech recognition",
" video analysis",
" ai",
" sdk",
" api client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06a1eca73d6cd9729121db465c927464f37408bf5be5f8ae21d48e682c51b392",
"md5": "b2b8278b29a4cb301de2303f93b0ec95",
"sha256": "d2f138599ca0c2579d2e04f1df48e941b71c018c4af269386189dd7f863f2e8b"
},
"downloads": -1,
"filename": "lattifai-0.4.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b2b8278b29a4cb301de2303f93b0ec95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 71815,
"upload_time": "2025-11-03T12:36:11",
"upload_time_iso_8601": "2025-11-03T12:36:11.745312Z",
"url": "https://files.pythonhosted.org/packages/06/a1/eca73d6cd9729121db465c927464f37408bf5be5f8ae21d48e682c51b392/lattifai-0.4.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 12:36:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lattifai",
"github_project": "lattifai-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lattifai"
}
