Metadata-Version: 2.4
Name: tube2note
Version: 1.0.2
Summary: YouTube channels, playlists and videos to a single Markdown file for NotebookLM
License: MIT
Project-URL: Homepage, https://github.com/omersusin/tube2note
Project-URL: Repository, https://github.com/omersusin/tube2note
Project-URL: Issues, https://github.com/omersusin/tube2note/issues
Keywords: youtube,transcript,markdown,notebooklm,cli,rag,yt-dlp,web-ui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp
Requires-Dist: certifi
Provides-Extra: pdf
Requires-Dist: fpdf2; extra == "pdf"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/omersusin/tube2note/main/docs/banner.png" alt="tube2note banner">

[![PyPI](https://img.shields.io/pypi/v/tube2note)](https://pypi.org/project/tube2note/)
[![Site](https://img.shields.io/badge/site-tube2note.github.io-blue)](https://omersusin.github.io/tube2note/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)

YouTube to readable text. Study, research, or feed it to NotebookLM. No tech skills needed. Your first file is ready in 10 minutes.

Tube2Note is a YouTube to text tool for students, researchers, and anyone who works with videos. It turns channels, playlists, or single videos into clean Markdown transcripts with timestamps and chapters. Then you can study them, search them offline, or feed them to AI tools like NotebookLM. If a run gets interrupted it picks up where it stopped. It can watch channels for new uploads, skip sponsor segments, write citations, and export SRT, PDF, EPUB, Anki flashcards, and Obsidian notes. It runs on Android, Windows, Mac, and Linux.

```bash
curl -fsSL https://omersusin.github.io/tube2note/install.sh | sh
```

**Features:** transcripts with timestamps & chapters · resume & watch mode · offline search · sponsor skip · citations (APA/MLA/Chicago/BibTeX) · SRT/VTT/TXT/PDF/EPUB/Anki/Obsidian exports · AI summarize/translate/transcribe · web UI, mobile app, Python API & MCP server.

## Walkthrough

**1. Install.** One command installs everything.

![install](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-0-setup.png)

**2. Preview.** Dry run shows what you will get, downloads nothing.

![preview](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-3-dryrun.png)

**3. Download.** One video in, transcript plus citation and subtitle files out.

![download](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-4-done.png)

**4. Search.** Find any sentence across all saved notes, offline.

![search](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-5-search.png)

**5. Check.** Doctor verifies every piece is working.

![doctor](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-2-doctor.png)

**6. Serve.** Run the browser UI on your own device.

![serve](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-6-serve.png)

**7. Watch.** Track channels in the background, fetch only new videos.

![watch](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-7-watch.png)

**8. Resume.** Same command again picks up where it stopped.

![resume](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-8-resume.png)

**9. Status.** See what finished, what was skipped, how big.

![status](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-9-status.png)

**10. Chapters.** Transcripts grouped by video chapters.

![chapters](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-10-chapters.png)

**11. Sponsor skip.** Ads cut before writing.

![sponsor](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-11-sponsor.png)

**12. Ebooks.** PDF and EPUB for readers.

![ebook](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-12-ebook.png)

**13. Obsidian.** Notes land in your vault with tags.

![obsidian](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-13-obsidian.png)

**14. Guided mode.** Just run `tube2note` and answer questions.

![guided](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-14-tui.png)

**15. AI.** Free key adds summaries, translation, transcription.

![ai](https://raw.githubusercontent.com/omersusin/tube2note/main/docs/shots/intro-15-ai.png)
offline search · sponsor skip · citations (APA/MLA/Chicago/BibTeX) ·
SRT/VTT/TXT/PDF/EPUB/Anki/Obsidian exports · AI summarize/translate/transcribe ·
web UI, mobile app, Python API & MCP server.

---

## Contents

- [What does it do?](#what-does-it-do)
- [Install: Android (phone)](#install-android-phone)
- [Install: Computer (Windows / Mac / Linux)](#install-computer-windows--mac--linux)
- [First run (step by step)](#first-run-step-by-step)
- [Everyday examples](#everyday-examples)
- [FAQ](#faq)
- [If something breaks](#if-something-breaks)
- [Advanced (optional)](#advanced-optional)

---

## What does it do?

1. You give it a YouTube link (video, channel, or playlist).
2. It downloads what people say in the videos, cleans it up, and makes one readable file.
3. You give that file to NotebookLM as a source and ask questions about the videos.

Example: convert a 200-video course channel into one file, then ask "what was covered in lesson 3?"

For developers: [MCP server](#advanced-optional), [Python API](#advanced-optional), [source code](https://github.com/omersusin/tube2note).

---

## Install: Android (phone)

We use the free **Termux** app to run it on your phone.

### 1. Install Termux

- **Install from F-Droid** (recommended): download F-Droid from [f-droid.org](https://f-droid.org), then install **Termux** from inside F-Droid.
- Do not use the Play Store version, it is outdated.

### 2. Install the needed pieces

Open Termux and type these lines **one by one**, pressing Enter after each:

```bash
pkg update
pkg install python
pip install tube2note
```

Wait for each to finish.

### 3. Check it

```bash
tube2note doctor
```

You'll see a checklist. If all is well, you're done. 🎉

> **Tip:** For long jobs (big channels) running overnight, type `termux-wake-lock` first so the phone doesn't fall asleep.

---

## Install: Computer (Windows / Mac / Linux)

### 1. Install Python (if missing)

- Download from [python.org/downloads](https://www.python.org/downloads/) and install.
- On Windows, tick **"Add python.exe to PATH"** during setup.
- Check: open a terminal (PowerShell/CMD on Windows, Terminal on Mac/Linux) and type `python --version`. You should see a version number.

### 2. Install the program

```bash
pip install tube2note
```

### 3. Check it

```bash
tube2note doctor
```

All good? You're ready. 🎉

---

## First run (step by step)

The easiest way is **guided mode**. Just type:

```bash
tube2note
```

It asks questions, you answer:

1. **Links:** paste your YouTube link (several allowed, separated by spaces).
2. **File name:** pick the output file name (press Enter to accept the suggestion).
3. **Folder:** pick where files are saved.
4. **Settings table:** confirm language, video count, and other settings.
5. **Start:** press Enter and let it work.

Your `.md` file lands in the folder when done. You can watch the progress bar.

> **Interrupted? No problem.** If the internet drops or you close the app, run the same command again. It resumes where it stopped.

---

## Everyday examples

Once comfortable, copy-paste these:

**Download a playlist:**
```bash
tube2note -o notes.md "PASTE_PLAYLIST_LINK"
```

**Download a channel, one file per video:**
```bash
tube2note -o channel.md --layout tree -d ./mynotes "PASTE_CHANNEL_LINK"
```

**Preview first (download nothing):**
```bash
tube2note --dry-run "PASTE_LINK"
```

**Auto-follow new videos:**
```bash
tube2note watch "PASTE_CHANNEL_LINK" -o channel.md --interval 60
```
(First run downloads everything, later runs only fetch new videos.)

**Search inside your downloads:**
```bash
tube2note search "your keyword" -d ./mynotes
```

**Make an EPUB for your e-reader:**
```bash
tube2note epub notes.md
```

**One-tap resume on your phone:** type `tube2note widget` (needs the Termux:Widget app).

---

## FAQ

**How do I give it to NotebookLM?**
Open NotebookLM → "Add source" → upload the `.md` file from your device. One file caps at 500,000 words; for bigger collections run with `--split-words 400000` to auto-split.

**What about videos without subtitles?**
They're skipped and listed under `## Skipped`. Optionally, AI transcription is available (see Advanced).

**It's slow / stuck — what now?**
YouTube sometimes throttles downloads. The program already slows down automatically. If nothing moves, stop it, **wait about 1 hour**, and run again. It resumes.

**My device turned off — start over?**
No. Run the same command again, it continues.

**Can I use it on the website?**
The site form needs a separately hosted backend. Easiest is the install above.

**Is it free?**
Yes, completely free and open source (MIT). Optional AI features use Google's free key.

---

## If something breaks

| Problem | Fix |
|---|---|
| `tube2note: command not found` | Install didn't finish. Redo the install steps. |
| Stuck for hours, no progress | Stop, wait 1 hour, run again (YouTube throttled you). |
| `No subtitles` | That video has no captions; it's skipped. If ALL fail, see `--transcribe` (Advanced). |
| Broken Turkish characters (`?` showing) | Run `tube2note doctor`, check the font line. |
| Disk full | Free up space and re-run. Half-written files are safe. |
| Still stuck | [Open an issue](https://github.com/omersusin/tube2note/issues) and describe it. |

---

## Advanced (optional)

For enthusiasts and developers. Not needed for normal use.

**Command-line options** (`tube2note --help` for all 40+):

| Flag | What it does |
|---|---|
| `--lang tr,en` | Transcript languages, in priority order |
| `--timestamps` / `--link-timestamps` | Keep `[MM:SS]` markers / make them clickable |
| `--ts-every 30` | One marker every 30s instead of every line |
| `--single-line` | Whole transcript on one line (for RAG) |
| `--split-words N` | Split output into N-word parts |
| `--since YYYY-MM-DD` | Only videos newer than date |
| `--resume-last` / `--redo ID` / `--fresh` | Resume last job / redo one video / start over |
| `--srt` / `--vtt` / `--txt` | Sidecar files per video |
| `--pdf` / `--epub` | Ebook exports |
| `--obsidian` | Tags + aliases for Obsidian vaults |
| `--chapters` | Group transcript by video chapters |
| `--sponsorblock` | Cut sponsor segments before writing |
| `--cite` | APA/MLA/Chicago citations + .bib/.ris |
| `--anki` | Flashcards from summaries (needs `--summarize`) |
| `--bilingual tr` | Source + translation side by side |
| `--jsonl` | Machine-readable lines for scripts |
| `-o -` | Print to terminal instead of file |
| `--cookies` / `--cookies-from-browser` | Age-gated / private videos |
| `--proxy` / `--workers` / `--yes` | Network, speed, skip confirmations |
| `watch --daemon` / `watch --stop` | Background channel watching |

**AI features** (free `GEMINI_API_KEY` from [aistudio.google.com](https://aistudio.google.com)):

| Flag | What it does |
|---|---|
| `--transcribe` | Transcribe videos with no captions |
| `--summarize` | Summary per video |
| `--translate tr` | Translate transcript |
| `--gemini-model` | Pick the model |

| Other | |
|---|---|
| `tube2note serve` | Browser page on your device to manage jobs |
| `tube2note status folder --json` | Machine-readable job status |
| `YT2MD_*` env / profiles | Defaults in `~/.config/yt2md/config.json` |
| Python / MCP / API | `import tube2note.api`, `tube2note mcp`, `tube2note serve-api` |

---

## Feedback (we read everything)

Found a bug? Want a feature? Tell us. It shapes what gets built next:

- 🐞 [Report a bug](https://github.com/omersusin/tube2note/issues/new?template=bug_report.md)
- 💡 [Request a feature](https://github.com/omersusin/tube2note/issues/new?template=feature_request.md)
- 💬 [General feedback](https://github.com/omersusin/tube2note/issues/new) (anything else)

Paste the failing command + the error text. Screenshots welcome.

## License

MIT — see [LICENSE](LICENSE).
