Podcast Automation

A small toolkit to download audio from YouTube, split it into 15-minute chunks, and send chunks to a Telegram bot. This repo provides:

• tgbot.py — a tiny script to send files to a Telegram chat using bot token and chat id from environment variables.
• download_and_send.py — end-to-end script that downloads a YouTube URL as MP3, splits the MP3 into chunks (default 15 minutes), stores the original and parts in a timestamped subfolder under outputs/, and sends the parts to Telegram.
• .env.example — an example environment file (placeholders only).

---

Requirements ✅

• Python 3.8+

• ffmpeg installed and available on your PATH (used for splitting audio and extracting audio during downloads)

  Alternatively, you can avoid installing a system ffmpeg by installing the Python packages imageio-ffmpeg and pydub (they are already included in requirements.txt). These packages will provide an ffmpeg binary that pydub can use.

• Recommended Python packages are listed in requirements.txt (install with pip install -r requirements.txt)

Suggested packages:

pip install -r requirements.txt

If you plan to use openai-based features later, install openai and set OPENAI_API_KEY in your environment.

---

Configuration 🔒

1. Copy .env.example to .env and fill in your values:

BOT_TOKEN=your_bot_token_here
CHAT_ID=your_chat_id_here
#DRY_RUN=0

2. .env is ignored by git (see .gitignore) so your secrets won't be committed accidentally.

3. Alternatively, set the variables directly in your shell:

export BOT_TOKEN=...
export CHAT_ID=...

Important: if a token was ever committed to the repo or .env.example, rotate it immediately via BotFather and update your local .env (see Security section).

---

Usage

Send any file using the bot (tgbot.py)

# dry run (just check env & show usage)
python tgbot.py path/to/file

# send one or more files
python tgbot.py file1.mp3 file2.mp3

tgbot.py reads BOT_TOKEN and CHAT_ID from environment (or a .env file if you use python-dotenv). It will raise helpful errors if variables are missing or if the API returns an error.

End-to-end download, split & send (download_and_send.py)

Download an audio track from YouTube, split it into 15-minute chunks (default), and send the parts to Telegram:

# dry run (downloads and splits, but does not send files)
python download_and_send.py "https://www.youtube.com/watch?v=..." --chunk 900 --dry-run

# actual run - will send parts to Telegram
python download_and_send.py "https://www.youtube.com/watch?v=..."

Flags:

• --chunk : chunk duration in seconds (default 900 = 15 minutes)
• --outdir : base output directory (default outputs)
• --dry-run : do everything except sending files
• --no-send : skip sending files (useful when you only want the split files)
• --validate : run a quick bot/chat validation (getMe & getChat) before sending

Output: the script creates a timestamped subfolder under outputs/ (e.g. outputs/My_Title_20251215T123456Z) containing the original mp3 and the split parts. The parts are named with a short indexed form such as 01_Joe Rogan Elon Musk.mp3.

---

Getting your Chat ID (if you don't know it)

1. Start a conversation with your bot (open @your_bot and send /start). Bots cannot message users who haven't messaged them first.
2. To discover chat ids programmatically, call getUpdates and inspect the result:

curl -s "https://api.telegram.org/bot$BOT_TOKEN/getUpdates" | jq .

Look for message -> chat -> id in the output and set CHAT_ID accordingly.

If getChat returns Bad Request: chat not found, verify you used the correct numeric id or that the bot has been messaged by that chat.

---

Security & Best Practices 🔐

• Rotate tokens: If a token was ever committed or exposed, rotate it immediately via BotFather.
• Remove secrets from history: if you need to remove a committed secret from repository history, use git filter-repo (recommended) or bfg repo-cleaner, and force-push to your remote and coordinate with your team.
• Prevent accidental commits: configure a pre-commit hook using detect-secrets or git-secrets and consider using GitHub secret scanning.
• Use repo secrets for CI: In GitHub Actions, store BOT_TOKEN and CHAT_ID as repository secrets and inject them into the workflow (see example below).

GitHub Actions example

name: Send file
on: workflow_dispatch
jobs:
  send:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Send file to Telegram
        env:
          BOT_TOKEN: ${{ secrets.BOT_TOKEN }}
          CHAT_ID: ${{ secrets.CHAT_ID }}
        run: |
          python download_and_send.py "https://www.youtube.com/watch?v=..."

---

Troubleshooting

• Error: Bad Request: chat not found

  • Cause: CHAT_ID incorrect or the target chat hasn't started the bot. Fix: message the bot from the target account and re-run getUpdates to check the chat id.

• ffmpeg not found

  • Install ffmpeg for your platform (e.g., sudo apt install ffmpeg on Debian/Ubuntu, brew install ffmpeg on macOS).

• yt-dlp warnings about JS runtimes

  • Some YouTube formats may require a JS runtime (see yt-dlp docs). The script works in most cases but you might see warnings.

---

File naming on small devices

Split parts are renamed to a short, indexed format (e.g., 01_Joe Rogan Elon Musk.mp3) to be easier to read on small devices like smartwatches. This keeps the index at the start so sorting is straightforward.

---

Contributing / Improvements

• Add concurrency or retry logic for sending large batches.
• Add a --confirm interactive flag for manual confirmation before sending.
• Integrate secret scanning into pre-commit or CI.

If you'd like, I can add one of these features for you — tell me which one and I'll implement it.

---

License

This project is provided as-is. Add a license file if you want an explicit license for your repo.