1→# YouTube Transcripts for macOS
     2→
     3→A native macOS app for fetching, managing, and reading YouTube video transcripts with AI-powered features.
     4→
     5→![macOS](https://img.shields.io/badge/macOS-14.0+-blue)
     6→![Swift](https://img.shields.io/badge/Swift-5.9+-orange)
     7→![License](https://img.shields.io/badge/license-MIT-green)
     8→
     9→## Features
    10→
    11→- **Fetch Transcripts** - Get transcripts from any YouTube video
    12→- **Multi-language Support** - Auto-detects and fetches transcripts in PT, EN, ES, FR
    13→- **Whisper Fallback** - Automatically transcribes audio when captions aren't available
    14→- **AI Summaries** - Generate summaries using local LM Studio
    15→- **AI Formatting** - Clean up and format transcripts with AI
    16→- **Text-to-Speech** - Listen to transcripts with highlighted text
    17→- **Annotations** - Highlight and underline important passages
    18→- **Notes** - Add personal notes to each transcript
    19→- **Export** - Save as Markdown or plain text
    20→- **Favorites** - Organize your transcript library
    21→
    22→## Screenshots
    23→
    24→| Library | Reading | New Transcript |
    25→|---------|---------|----------------|
    26→| Browse saved transcripts | Read with TTS | Fetch new videos |
    27→
    28→## Installation
    29→
    30→### Prerequisites
    31→
    32→1. **macOS 14.0+** (Sonoma or later)
    33→2. **Xcode 15+**
    34→3. **Python 3.9+**
    35→4. **ffmpeg** (for audio conversion)
    36→
    37→### Setup
    38→
    39→1. Clone the repository:
    40→```bash
    41→git clone https://github.com/leandro1416/YouTubeTranscripts-macOS.git
    42→cd YouTubeTranscripts-macOS
    43→```
    44→
    45→2. Install Python dependencies:
    46→```bash
    47→pip3 install pytubefix        # Primary audio downloader
    48→pip3 install yt-dlp           # Fallback downloader
    49→pip3 install youtube_transcript_api  # Caption fetcher
    50→pip3 install openai-whisper   # Local transcription
    51→```
    52→
    53→3. Install ffmpeg:
    54→```bash
    55→brew install ffmpeg
    56→```
    57→
    58→4. Open in Xcode and build:
    59→```bash
    60→open YouTubeTranscripts.xcodeproj
    61→```
    62→
    63→5. Press `Cmd+R` to build and run.
    64→
    65→## Usage
    66→
    67→### Fetching a Transcript
    68→
    69→1. Click **Add** or press `Cmd+N`
    70→2. Paste a YouTube URL
    71→3. Select language (optional)
    72→4. Click **Get Transcript**
    73→
    74→### Transcript Sources
    75→
    76→The app tries multiple methods to get transcripts:
    77→
    78→| Priority | Method | When Used |
    79→|----------|--------|-----------|
    80→| 1 | YouTube Captions | Video has subtitles |
    81→| 2 | pytubefix + Whisper | No captions available |
    82→| 3 | yt-dlp + Whisper | pytubefix fails |
    83→
    84→### AI Features (Optional)
    85→
    86→To enable AI features, run [LM Studio](https://lmstudio.ai) locally:
    87→
    88→1. Download and install LM Studio
    89→2. Load a model (e.g., Llama, Mistral)
    90→3. Start the local server on port 1234
    91→4. AI features will automatically connect
    92→
    93→## Architecture
    94→
    95→```
    96→YouTubeTranscripts-macOS/
    97→├── Sources/
    98→│   ├── App/                 # App entry point
    99→│   ├── Core/                # Configuration, formatters
   100→│   ├── Models/              # SwiftData models
   101→│   ├── Services/            # Business logic
   102→│   │   ├── MCPService       # YouTube caption fetcher
   103→│   │   ├── WhisperService   # Local transcription
   104→│   │   ├── AudioDownloadService  # pytubefix/yt-dlp
   105→│   │   ├── AIService        # LM Studio integration
   106→│   │   └── TTSService       # Text-to-speech
   107→│   ├── ViewModels/          # MVVM view models
   108→│   └── Views/               # SwiftUI views
   109→└── WHISPER-SETUP.md         # Detailed setup guide
   110→```
   111→
   112→## Technologies
   113→
   114→- **SwiftUI** - Native macOS UI
   115→- **SwiftData** - Local persistence
   116→- **AVFoundation** - Text-to-speech
   117→- **Python** - Backend scripts (Whisper, yt-dlp)
   118→- **OpenAI Whisper** - Speech-to-text
   119→- **pytubefix** - YouTube audio download
   120→
   121→## Troubleshooting
   122→
   123→### "No transcript available"
   124→
   125→The video might not have captions. The app will automatically try to:
   126→1. Download the audio
   127→2. Transcribe with Whisper
   128→
   129→This takes longer but works for any video.
   130→
   131→### "Download failed (403 Forbidden)"
   132→
   133→YouTube occasionally blocks downloads. Solutions:
   134→- Wait a few minutes and try again
   135→- Make sure `pytubefix` is up to date: `pip3 install -U pytubefix`
   136→- Log into YouTube in your browser (cookies help)
   137→
   138→### "Whisper not found"
   139→
   140→Install Whisper:
   141→```bash
   142→pip3 install openai-whisper
   143→```
   144→
   145→### "ffmpeg not found"
   146→
   147→Install ffmpeg:
   148→```bash
   149→brew install ffmpeg
   150→```
   151→
   152→## Contributing
   153→
   154→Contributions are welcome! Please:
   155→
   156→1. Fork the repository
   157→2. Create a feature branch
   158→3. Make your changes
   159→4. Submit a pull request
   160→
   161→## License
   162→
   163→MIT License - see [LICENSE](LICENSE) for details.
   164→
   165→## Acknowledgments
   166→
   167→- [OpenAI Whisper](https://github.com/openai/whisper) - Speech recognition
   168→- [pytubefix](https://github.com/JuanBindez/pytubefix) - YouTube downloads
   169→- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Video/audio extraction
   170→- [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api) - Caption fetching
   171→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>