---
description: Export format standards for transcript outputs for src/services/**/* and src/cli/**/*
alwaysApply: false
---
# Export Formats Rule

## Core Principles
- **Dual Format Support**: Always export in both JSON and TXT formats
- **Complete Data in JSON**: Preserve all metadata and structure in JSON
- **Human Readability in TXT**: Optimize TXT for human consumption
- **Consistent Naming**: Follow standard naming conventions
- **Format Restrictions**: Limit to JSON and TXT only

## Implementation Patterns

### JSON Export Format
```json
{
  "id": "transcript-123",
  "metadata": {
    "title": "Interview with Dr. Smith",
    "duration": 1823.5,
    "language": "en-US",
    "speakers": 2,
    "created_at": "2023-06-15T10:30:45.123456Z"
  },
  "segments": [
    {
      "id": 1,
      "speaker": "Speaker 1",
      "start": 0.0,
      "end": 15.2,
      "text": "Welcome to our interview series. Today we're speaking with Dr. Smith about...",
      "confidence": 0.98
    },
    {
      "id": 2,
      "speaker": "Speaker 2",
      "start": 15.5,
      "end": 45.8,
      "text": "Thank you for having me. I'd like to discuss the recent developments in...",
      "confidence": 0.95
    }
  ]
}
```

### TXT Export Format
```
Interview with Dr. Smith
Recorded: June 15, 2023
Duration: 30:23

[00:00:00] Speaker 1: Welcome to our interview series. Today we're speaking with Dr. Smith about...

[00:00:15] Speaker 2: Thank you for having me. I'd like to discuss the recent developments in...
```

### File Naming
```python
# ✅ DO: Use consistent naming conventions
def generate_export_filenames(transcript_id: str) -> Tuple[Path, Path]:
    """Generate export filenames for a transcript."""
    json_path = Path(f"exports/json/{transcript_id}.json")
    txt_path = Path(f"exports/txt/{transcript_id}.txt")
    return json_path, txt_path
```

### Export Generation
```python
# ✅ DO: Generate both formats together
async def export_transcript(transcript_id: str) -> Tuple[Path, Path]:
    """Export transcript in both JSON and TXT formats."""
    transcript = await get_transcript(transcript_id)
    
    # Generate paths
    json_path, txt_path = generate_export_filenames(transcript_id)
    
    # Export JSON (complete data)
    with open(json_path, "w") as f:
        json.dump(transcript, f, indent=2)
    
    # Export TXT (human-readable)
    with open(txt_path, "w") as f:
        f.write(format_transcript_for_humans(transcript))
    
    return json_path, txt_path
```

### Anti-Patterns
```python
# ❌ DON'T: Export only one format
def export_json_only(transcript_id: str) -> Path:
    # Missing TXT export!
    pass

# ❌ DON'T: Use inconsistent naming
json_path = Path(f"exports/{transcript_id}_output.json")  # Wrong!
txt_path = Path(f"exports/transcript_{transcript_id}.txt")  # Wrong!

# ❌ DON'T: Export to unsupported formats
def export_to_csv(transcript_id: str) -> Path:  # Wrong!
    pass
```

## Export Requirements

- **JSON Export:**
  - Must include the complete transcript structure.
  - All segments, speaker labels, timestamps, and any associated metadata (such as language, confidence scores, or custom tags) must be preserved.
  - The JSON should be well-formed and valid according to the transcript schema.
  - Ensure that nested structures (e.g., segments within speakers) are accurately represented.

- **TXT Export:**
  - Should be formatted for maximum human readability.
  - Include clear speaker labels and timestamps where appropriate.
  - Use consistent indentation and spacing to enhance clarity.
  - Exclude metadata that is not relevant for human readers, focusing on the transcript content itself.

- **File Naming:**
  - Use a consistent naming convention: `{id}.json` for JSON exports and `{id}.txt` for TXT exports, where `{id}` is a unique identifier for the transcript.
  - Avoid using spaces or special characters in filenames.

- **Format Restrictions:**
  - Do not export transcripts in any formats other than JSON and TXT.
  - Do not include additional or more complex formats (such as XML, CSV, DOCX, or PDF).

- **Additional Guidelines:**
  - Ensure that both export files are generated together for each transcript.
  - Validate the output files to confirm they meet the above requirements before making them available for download or further processing.