Skip to content

Commit 33b0bd9

Browse files
MitCode85MitCode85
authored
v1.0.0-rc.1: initial public release (yt-dlp + FFmpeg + MP3Gain, i18n, tooltips, PyInstaller spec)
- Core/GUI separation finalized: processing in workbench_core.py; GUI handles UI only - Unified tool resolver (resolve_tool_path) used across modules - Full i18n (EN/FR) incl. Help/About and translatable tooltips; language menu + persistence - Tooltip manager: race-safe, configurable delay/wrap, persisted - Help/About: centered, diagnostics copy, Troubleshooting link - Tests: resolver, cookies conversion, ID3/join (mocked) - Build: PyInstaller spec + Windows helper script - Docs: README, HELP.md, CONTRIBUTING, CHANGELOG; MIT LICENSE - GitHub Actions (if .github/workflows/build.yml is included): CI builds for Windows/macOS/Linux + release on tags - .gitignore includes dist/build/venv/caches/config.json
1 parent 8cae419 commit 33b0bd9

27 files changed

+3777
-3
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Changelog
2+
3+
## 1.0.0-rc.1
4+
- Initial release candidate.

‎CONTRIBUTING.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Contributing
2+
3+
Thank you for your interest in contributing!
4+
5+
## Development Setup
6+
7+
- Python 3.9+ required
8+
- Recommended: [uv](https://github.com/astral-sh/uv) for environment management
9+
10+
```bash
11+
uv venv
12+
uv sync
13+
```
14+
15+
- Fallback:
16+
```bash
17+
pip install -r requirements.txt
18+
```
19+
20+
## Coding Standards
21+
22+
- Code style: [Ruff](https://github.com/charliermarsh/ruff)
23+
- Type checking: [mypy](http://mypy-lang.org/)
24+
- Security lint: [bandit](https://bandit.readthedocs.io/)
25+
26+
Run checks with:
27+
28+
```bash
29+
make lint
30+
```
31+
32+
## Submitting Changes
33+
34+
1. Fork and branch off `main`.
35+
2. Ensure lint/tests pass (`make test lint`).
36+
3. Update docs (README, CHANGELOG).
37+
4. Submit a PR.
38+
39+
---
40+
41+
This project may adopt a DCO/CLA in the future.
42+
43+
44+
### Quickstart scripts
45+
46+
If you don't want to use Make:
47+
48+
- Windows PowerShell:
49+
```powershell
50+
./setup-venv.ps1
51+
```
52+
53+
- Linux/macOS:
54+
```bash
55+
./setup-venv.sh
56+
```
57+
58+
These scripts will try **uv** first (if installed), else fall back to `python -m venv` and pip installs.
59+
60+
61+
## Security Linting
62+
63+
We use [Bandit](https://bandit.readthedocs.io/) for static security checks.
64+
65+
- Config: in `pyproject.toml` under `[tool.bandit]`
66+
- Run locally with `make security`
67+
68+
69+
## Pre-commit Hooks
70+
71+
We use [pre-commit](https://pre-commit.com/) to run Ruff (lint/format) and Bandit (security linting) automatically on staged files.
72+
73+
### Setup
74+
75+
Install pre-commit (using pip or uv):
76+
```bash
77+
pip install pre-commit
78+
# or: uv pip install pre-commit
79+
```
80+
81+
Enable the hooks:
82+
```bash
83+
pre-commit install
84+
```
85+
86+
Now, every time you commit, Ruff and Bandit will run automatically on the files you changed.

‎HELP.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# YT Audio Workbench — Help
2+
Welcome to the help documentation for YT Audio Workbench. This guide will walk you through the main features and options available in the application.
3+
4+
## Table of Contents
5+
- [Getting Started](#getting-started)
6+
- [Main Window Explained](#main-window-explained)
7+
- [URL & Output](#url--output)
8+
- [Cookies](#cookies)
9+
- [Download & Formatting](#download--formatting)
10+
- [Filename & Options](#filename--options)
11+
- [Joining](#joining)
12+
- [System Dependencies](#system-dependencies)
13+
- [Controls & Log](#controls--log)
14+
- [Troubleshooting](#troubleshooting)
15+
- [Tool Not Found (ffmpeg, mp3gain)](#tool-not-found-ffmpeg-mp3gain)
16+
- [Downloads are Slow or Failing](#downloads-are-slow-or-failing)
17+
- [Private/Members-Only Videos Not Working](#privatevideos)
18+
19+
## Getting Started <a name="getting-started"></a>
20+
The primary purpose of this tool is to create high-quality, consistent MP3 backups from a YouTube URL (either a single video or a playlist).
21+
22+
**Basic Workflow:**
23+
1. Paste a YouTube URL into the top field.
24+
2. Select an Output folder where the files will be saved.
25+
3. Choose your desired Bitrate and Sample Rate.
26+
4. Click Run.
27+
28+
## Main Window Explained <a name="main-window-explained"></a>
29+
30+
### URL & Output <a name="url--output"></a>
31+
**Playlist or video URL:** The source URL from YouTube.
32+
**Output folder:** The main directory where all files and logs will be saved.
33+
**Use per-run subfolder:** (Recommended) When checked, each time you click "Run", a new subfolder with a timestamp (e.g., `run_20250824_193000`) will be created inside your output folder. This is the safest way to keep download sessions separate and ensures the "Join" feature works correctly.
34+
35+
### Cookies <a name="cookies"></a>
36+
**Cookies file:** You can provide a `cookies.txt` (Netscape format) or a `.json` file exported from a browser extension like "Cookie-Editor". The application will automatically convert `.json` files.
37+
**Use browser cookies:** Alternatively, select a browser and the application will attempt to use its live cookie data.
38+
39+
### Download & Formatting <a name="download--formatting"></a>
40+
**Sample rate:** Enforces a consistent audio sample rate for all files. `44100 Hz` is standard for CD quality, while `48000 Hz` is common for video.
41+
**Bitrate (kbps):** Sets the quality of the MP3 file. `192` is good quality, `320` is the highest quality for MP3.
42+
**Delay between items (s):** A pause between downloading each item in a playlist to avoid being rate-limited by the server.
43+
**Playlist format:** Creates a playlist file (`.m3u` or `.m3u8`) of the downloaded tracks for easy playback.
44+
45+
### Filename & Options <a name="filename--options"></a>
46+
**Add numbering:** Prefixes filenames with a number (e.g., `001 - ...`, `002 - ...`).
47+
**Include YouTube ID in filename:** Appends the unique YouTube video ID in brackets (e.g., `... [dQw4w9WgXcQ].mp3`). *Note:* Brackets can cause issues with some older media players.
48+
**Sanitize filenames:** (Recommended) Removes special characters from filenames that can cause problems with playlists or scripts.
49+
**Use download archive:** The app will keep a record of downloaded files in `download_archive.txt`. If you run the same playlist again, it will skip any files it has already downloaded.
50+
**Normalize with MP3Gain:** Uses the mp3gain tool to adjust the volume of all tracks to a standard level without losing quality.
51+
**De-duplicate artist in filename:** Removes duplicated artist names from filenames (e.g., `Artist - Artist - Title` → `Artist - Title`).
52+
**Validate with ffprobe:** Validates sample rate/format using `ffprobe` after conversion.
53+
**Verbose yt-dlp logging:** Runs yt-dlp in verbose mode for troubleshooting.
54+
**Fallback to progressive:** If standard DASH download yields no audio, retry with progressive HTTP streams.
55+
56+
### Joining <a name="joining"></a>
57+
**Join into one MP3:** Enables joining to combine all downloaded MP3s into a single large file.
58+
**Name:** Filename for the final combined MP3.
59+
**Write CUE for joined file:** Creates a `.cue` file with accurate `INDEX 01` markers.
60+
**Embed ID3 chapters:** Embeds chapter markers directly into the joined MP3 (requires `mutagen`).
61+
**Randomize order when joining:** Shuffles the playlist before combining.
62+
**Keep temp WAVs:** Keep intermediate WAVs from the join pipeline (useful for debugging).
63+
**Write VLC segment playlist:** Creates an `.m3u` playlist that points to chapter start/stop times inside the joined MP3 for VLC.
64+
65+
### System Dependencies <a name="system-dependencies"></a>
66+
**Verify Tools:** Checks if `yt-dlp`, `ffmpeg`, `ffprobe`, and `mp3gain` are installed and accessible.
67+
**Check & Install System Deps:** Attempts automatic installation (Windows: `winget`; macOS: `brew`; Linux: `apt/dnf/pacman`).
68+
69+
### Controls & Log <a name="controls--log"></a>
70+
**Run/Cancel:** Starts or stops the current process.
71+
**Progress Bar:** Shows determinate progress during downloads and joining.
72+
**Log Window:** Displays detailed information about the ongoing process. Right-click to copy or clear the log.
73+
74+
## Troubleshooting <a name="troubleshooting"></a>
75+
### Tool Not Found (ffmpeg, mp3gain) <a name="tool-not-found-ffmpeg-mp3gain"></a>
76+
If the log reports a tool is "missing" even after you've installed it, try restarting the application so PATH changes are picked up.
77+
78+
### Downloads are Slow or Failing <a name="downloads-are-slow-or-failing"></a>
79+
Try increasing the **Delay between items** to 5 seconds or more. Check your internet connection. The video may have been removed or be region-locked.
80+
81+
### Private/Members-Only Videos Not Working <a name="privatevideos"></a>
82+
This almost always means there is an issue with your cookies. Ensure you are logged into YouTube in your browser. Use a browser extension like "Cookie-Editor" to export your YouTube cookies to a `.json` file. Select that `.json` file in the "Cookies" section of the app and try again.

‎LICENSE

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2025 MitCode85
3+
Copyright (c) 2025 YT Audio Workbench
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎Makefile

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Minimal developer workflow
2+
.PHONY: dev run lint test export clean
3+
4+
dev:
5+
uv venv || python -m venv .venv
6+
uv sync || pip install -r requirements.txt ruff mypy bandit
7+
8+
run:
9+
python yt_audio_backup_gui.py
10+
11+
lint:
12+
ruff check .
13+
mypy --install-types --non-interactive || true
14+
15+
test:
16+
python - <<'PY'
17+
print("Smoke test: import OK")
18+
import yt_dlp
19+
print("yt_dlp version:", getattr(yt_dlp, "__version__", "unknown"))
20+
PY
21+
22+
export:
23+
# lock and export a pip requirements file from uv if available
24+
uv export --no-dev --format requirements-txt > requirements.lock.txt || echo "uv not available"
25+
26+
clean:
27+
rm -rf .mypy_cache .ruff_cache .pytest_cache dist build *.spec
28+
29+
30+
# ---- Binary builds (PyInstaller) ----
31+
.PHONY: build build-win build-mac build-linux distclean
32+
33+
build:
34+
pyinstaller yt_audio_backup.spec
35+
36+
build-win:
37+
pyinstaller yt_audio_backup.spec
38+
39+
build-mac:
40+
pyinstaller yt_audio_backup.spec
41+
42+
build-linux:
43+
pyinstaller yt_audio_backup.spec
44+
45+
distclean:
46+
rm -rf build dist *.spec
47+
48+
49+
# ---- Dependency check ----
50+
.PHONY: check-deps
51+
52+
check-deps:
53+
@echo "Checking for ffmpeg, ffprobe, mp3gain..."
54+
@if command -v ffmpeg >/dev/null 2>&1; then echo "✅ ffmpeg: $$(command -v ffmpeg)"; else echo "❌ ffmpeg NOT found"; fi
55+
@if command -v ffprobe >/dev/null 2>&1; then echo "✅ ffprobe: $$(command -v ffprobe)"; else echo "❌ ffprobe NOT found"; fi
56+
@if command -v mp3gain >/dev/null 2>&1; then echo "✅ mp3gain: $$(command -v mp3gain)"; else echo "❌ mp3gain NOT found"; fi

‎ONBOARDING.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
## Developer Onboarding Guide
2+
3+
Welcome to the project! Here’s how to get your development environment set up in a few minutes.
4+
5+
### 1. Prerequisites
6+
7+
Before you begin, make sure you have the following installed on your system:
8+
9+
* **Python 3.9+**
10+
* **Git**
11+
* **ffmpeg** & **ffprobe**
12+
* **mp3gain** (optional, but recommended)
13+
14+
*You can run the `check-deps.sh` (macOS/Linux) or `check-deps.ps1` (Windows) script in the repository to verify the external tools.*
15+
16+
---
17+
18+
### 2. Project Setup
19+
20+
The project includes setup scripts that will handle creating a virtual environment and installing all necessary Python packages.
21+
22+
1. **Clone the repository:**
23+
```bash
24+
git clone <repository-url>
25+
cd <repository-folder>
26+
```
27+
28+
2. **Run the setup script for your OS:**
29+
30+
* For **Windows** (in PowerShell):
31+
```powershell
32+
.\setup-venv.ps1
33+
```
34+
* For **macOS / Linux** (in your terminal):
35+
```bash
36+
bash setup-venv.sh
37+
```
38+
39+
3. **Activate the virtual environment:**
40+
41+
* For **Windows** (in PowerShell):
42+
```powershell
43+
.\.venv\Scripts\Activate.ps1
44+
```
45+
* For **macOS / Linux** (in your terminal):
46+
```bash
47+
source .venv/bin/activate
48+
```
49+
50+
---
51+
52+
### 3. Running the Application
53+
54+
With the virtual environment active, you can run the application with a simple command:
55+
56+
```bash
57+
python yt_audio_backup_gui.py
58+
```
59+
60+
---
61+
62+
### 4. Development Workflow
63+
64+
This project uses standard tools to maintain code quality.
65+
66+
* **Linting & Testing:** Use the `Makefile` for common tasks.
67+
```bash
68+
# Run all linters and type checkers
69+
make lint
70+
71+
# Run a quick smoke test
72+
make test
73+
```
74+
75+
* **Pre-commit Hooks (Recommended):** The project is set up with pre-commit hooks to automatically format code and run checks before you commit. To enable this, run:
76+
```bash
77+
# Install the hooks into your local .git folder
78+
pre-commit install
79+
```
80+
81+
That's it! You're ready to start developing.

‎README.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# YT-Audio-Workbench
1+
# YT Audio Workbench
22

3-
> Reliability-first, cross-platform (Windows/macOS/Linux) Python GUI for yt-dlp + FFmpeg with optional MP3Gain. Turn YouTube videos & playlists into high-quality MP3 with proper ID3 tags, loudness normalization (ReplayGain), playlist/CUE options, robust tool checks, and multilingual support (i18n: EN/FR) support.
3+
> Reliability-first, cross-platform (Windows/macOS/Linux) Python GUI for yt-dlp + FFmpeg with optional MP3Gain. Convert YouTube videos & playlists into high-quality MP3 with proper ID3 tags, ReplayGain loudness normalization, playlist/CUE options, robust tool checks, and multilingual (i18n: EN/FR) support.
44
55
## Features
66
- **Reliability-first pipeline**: robust tool checks, clear error messages, cancellable jobs, logs.
@@ -73,3 +73,8 @@ PRs welcome! Please run tests:
7373
pip install pytest
7474
pytest -q
7575
```
76+
77+
78+
## Downloads
79+
- Unsigned binaries are produced by CI for Windows, macOS (x64 & arm64), and Linux. See **Actions → Build** artifacts or tagged releases.
80+
- macOS Gatekeeper: right‑click → Open the first time. Windows SmartScreen: choose **More info → Run anyway**.

‎SECURITY.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
Security updates will be applied to the latest release branch.
6+
7+
## Reporting a Vulnerability
8+
9+
If you discover a security vulnerability, please responsibly disclose it:
10+
11+
- Email: security@example.com (replace with project maintainer contact)
12+
- Or open a private security advisory on GitHub
13+
14+
We will acknowledge receipt within 48 hours and provide regular updates until the issue is resolved.
15+

0 commit comments

Comments
 (0)