Skip to content

Commit df333a6

Browse files
MitCode85MitCode85
committed
fix: help.md formatting
1 parent 77c9169 commit df333a6

File tree

1 file changed

+76
-56
lines changed

1 file changed

+76
-56
lines changed

‎docs/HELP.md

Lines changed: 76 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,92 @@
11
# YT Audio Workbench — Help
22

3+
Welcome to the help documentation for YT Audio Workbench. This guide will walk you through the main features and options available in the application.
4+
35
## Table of Contents
4-
- [Table of Contents](#table-of-contents)
5-
- [Getting StartedThe primary purpose of this tool is to create high-quality, consistent MP3 backups from a YouTube URL (either a single video or a playlist).](#getting-startedthe-primary-purpose-of-this-tool-is-to-create-high-quality-consistent-mp3-backups-from-a-youtube-url-either-a-single-video-or-a-playlist)
6-
- [Paste a YouTube URL into the top field.](#paste-a-youtube-url-into-the-top-field)
7-
- [Select an Output folder where the files will be saved.](#select-an-output-folder-where-the-files-will-be-saved)
8-
- [Choose your desired Bitrate and Sample Rate.](#choose-your-desired-bitrate-and-sample-rate)
9-
- [Click Run.](#click-run)
10-
- [Main Window Explained### URL & Output**Playlist or video URL:** The source URL from YouTube.](#main-window-explained-url-outputplaylist-or-video-url-the-source-url-from-youtube)
11-
- [Cookies**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.](#cookiescookies-file-you-can-provide-a-cookiestxt-netscape-format-or-a-json-file-exported-from-a-browser-extension-like-cookie-editor-the-application-will-automatically-convert-json-files)
12-
- [Download & Formatting**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.](#download-formattingsample-rate-enforces-a-consistent-audio-sample-rate-for-all-files-44100-hz-is-standard-for-cd-quality-while-48000-hz-is-common-for-video)
13-
- [Filename & Options**Add numbering:** Prefixes filenames with a number (e.g., `001 - ...`, `002 - ...`).](#filename-optionsadd-numbering-prefixes-filenames-with-a-number-eg-001---002---)
14-
- [Joining**Join into one MP3:** Enables joining to combine all downloaded MP3s into a single large file.](#joiningjoin-into-one-mp3-enables-joining-to-combine-all-downloaded-mp3s-into-a-single-large-file)
15-
- [System Dependencies**Verify Tools:** Checks if `yt-dlp`, `ffmpeg`, `ffprobe`, and `mp3gain` are installed and accessible.](#system-dependenciesverify-tools-checks-if-yt-dlp-ffmpeg-ffprobe-and-mp3gain-are-installed-and-accessible)
16-
- [Controls & Log**Run/Cancel:** Starts or stops the current process.](#controls-logruncancel-starts-or-stops-the-current-process)
17-
- [Troubleshooting### Tool Not Found (ffmpeg, mp3gain)If the log reports a tool is "missing" even after you've installed it, try restarting the application so PATH changes are picked up.](#troubleshooting-tool-not-found-ffmpeg-mp3gainif-the-log-reports-a-tool-is-missing-even-after-youve-installed-it-try-restarting-the-application-so-path-changes-are-picked-up)
18-
- [Downloads are Slow or FailingTry increasing the **Delay between items** to 5 seconds or more. Check your internet connection. The video may have been removed or be region-locked.](#downloads-are-slow-or-failingtry-increasing-the-delay-between-items-to-5-seconds-or-more-check-your-internet-connection-the-video-may-have-been-removed-or-be-region-locked)
19-
- [Private/Members-Only Videos Not WorkingThis 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.](#privatemembers-only-videos-not-workingthis-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)
6+
- [Getting Started](#getting-started)
7+
- [Main Window Explained](#main-window-explained)
8+
- [Core Settings](#core-settings)
9+
- [Cookies](#cookies)
10+
- [Download & Formatting](#download--formatting)
11+
- [Filename & Options](#filename--options)
12+
- [Joining](#joining)
13+
- [System Dependencies](#system-dependencies)
14+
- [Controls & Log](#controls--log)
15+
- [Troubleshooting](#troubleshooting)
16+
- [Tool Not Found Errors](#tool-not-found-errors)
17+
- [Downloads are Slow or Failing](#downloads-are-slow-or-failing)
18+
- [Private/Members-Only Videos Not Working](#privatemembers-only-videos-not-working)
2019

21-
Welcome to the help documentation for YT Audio Workbench. This guide will walk you through the main features and options available in the application.
20+
## Getting Started
21+
22+
The primary purpose of this tool is to create high-quality, consistent MP3 backups from a YouTube URL, whether it's a single video or a playlist.
23+
24+
#### Basic Workflow:
25+
1. **Paste** a YouTube URL into the top field.
26+
2. **Select** an Output folder where the files will be saved.
27+
3. **Choose** your desired Bitrate and Sample Rate.
28+
4. **Click** the **Run** button.
29+
30+
## Main Window Explained
2231

23-
## Getting StartedThe primary purpose of this tool is to create high-quality, consistent MP3 backups from a YouTube URL (either a single video or a playlist).
32+
This section details each option available in the application's main window.
2433

25-
**Basic Workflow:**
26-
## Paste a YouTube URL into the top field.
27-
## Select an Output folder where the files will be saved.
28-
## Choose your desired Bitrate and Sample Rate.
29-
## Click Run.
34+
### Core Settings
35+
- **Playlist or video URL:** The source URL from YouTube.
36+
- **Output folder:** The main directory where all files and logs will be saved.
37+
- **Use per-run subfolder:** (Recommended) When checked, each time you click "Run", a new subfolder with a timestamp (e.g., `run_20250826_164000`) will be created inside your output folder. This is the safest way to keep download sessions separate and ensures the "Join" feature works correctly.
3038

31-
## Main Window Explained### URL & Output**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.
39+
### Cookies
40+
- **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 if needed.
41+
- **Use browser cookies:** Alternatively, select a browser (e.g., Chrome, Firefox) and the application will attempt to use its live cookie data to access private content.
3442

35-
### Cookies**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.
36-
**Use browser cookies:** Alternatively, select a browser and the application will attempt to use its live cookie data.
43+
### Download & Formatting
44+
- **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.
45+
- **Bitrate (kbps):** Sets the quality of the MP3 file. `192` provides good quality, while `320` is the highest quality available for the MP3 format.
46+
- **Delay between items (s):** A pause (in seconds) between downloading each item in a playlist to avoid being rate-limited by YouTube's servers.
47+
- **Playlist format:** Creates a playlist file (`.m3u` or `.m3u8`) of the downloaded tracks for easy playback in media players.
3748

38-
### Download & Formatting**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.
39-
**Bitrate (kbps):** Sets the quality of the MP3 file. `192` is good quality, `320` is the highest quality for MP3.
40-
**Delay between items (s):** A pause between downloading each item in a playlist to avoid being rate-limited by the server.
41-
**Playlist format:** Creates a playlist file (`.m3u` or `.m3u8`) of the downloaded tracks for easy playback.
49+
### Filename & Options
50+
- **Add numbering:** Prefixes filenames with a number (e.g., `001_...`, `002_...`).
51+
- **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.
52+
- **Sanitize filenames:** (Recommended) Removes special characters from filenames that can cause problems with file systems, playlists, or scripts.
53+
- **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.
54+
- **Normalize with MP3Gain:** Uses the `mp3gain` tool to adjust the volume of all tracks to a standard level without re-encoding or losing quality.
55+
- **De-duplicate artist in filename:** Cleans up filenames by removing repeated artist names (e.g., `Artist - Artist - Title` becomes `Artist - Title`).
56+
- **Validate with ffprobe:** Uses `ffprobe` to validate the sample rate and format after the audio conversion is complete.
57+
- **Verbose yt-dlp logging:** Runs the underlying `yt-dlp` tool in verbose mode, which is useful for troubleshooting download issues.
58+
- **Fallback to progressive:** If the standard download method (DASH) yields no audio, this option will retry the download using older progressive HTTP streams.
4259

43-
### Filename & Options**Add numbering:** Prefixes filenames with a number (e.g., `001 - ...`, `002 - ...`).
44-
**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.
45-
**Sanitize filenames:** (Recommended) Removes special characters from filenames that can cause problems with playlists or scripts.
46-
**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.
47-
**Normalize with MP3Gain:** Uses the mp3gain tool to adjust the volume of all tracks to a standard level without losing quality.
48-
**De-duplicate artist in filename:** Removes duplicated artist names from filenames (e.g., `Artist - Artist - Title` → `Artist - Title`).
49-
**Validate with ffprobe:** Validates sample rate/format using `ffprobe` after conversion.
50-
**Verbose yt-dlp logging:** Runs yt-dlp in verbose mode for troubleshooting.
51-
**Fallback to progressive:** If standard DASH download yields no audio, retry with progressive HTTP streams.
60+
### Joining
61+
- **Join into one MP3:** Enables the joining feature to combine all downloaded MP3s into a single large audio file.
62+
- **Name:** The filename for the final combined MP3.
63+
- **Write CUE for joined file:** Creates a `.cue` sheet with accurate `INDEX 01` markers for each track, allowing players to skip between chapters.
64+
- **Embed ID3 chapters:** Embeds chapter markers directly into the joined MP3 file (requires the `mutagen` library).
65+
- **Randomize order when joining:** Shuffles the playlist before combining the files into one.
66+
- **Keep temp WAVs:** Prevents the deletion of intermediate WAV files used during the joining process. This is useful for debugging.
67+
- **Write VLC segment playlist:** Creates a special `.m3u` playlist that points to the specific start and stop times for each chapter inside the joined MP3, for use with VLC Media Player.
5268

53-
### Joining**Join into one MP3:** Enables joining to combine all downloaded MP3s into a single large file.
54-
**Name:** Filename for the final combined MP3.
55-
**Write CUE for joined file:** Creates a `.cue` file with accurate `INDEX 01` markers.
56-
**Embed ID3 chapters:** Embeds chapter markers directly into the joined MP3 (requires `mutagen`).
57-
**Randomize order when joining:** Shuffles the playlist before combining.
58-
**Keep temp WAVs:** Keep intermediate WAVs from the join pipeline (useful for debugging).
59-
**Write VLC segment playlist:** Creates an `.m3u` playlist that points to chapter start/stop times inside the joined MP3 for VLC.
69+
### System Dependencies
70+
- **Verify Tools:** Checks if `yt-dlp`, `ffmpeg`, `ffprobe`, and `mp3gain` are installed and accessible in the system's PATH.
71+
- **Check & Install System Deps:** Attempts to automatically install the required tools using common package managers (Windows: `winget`; macOS: `brew`; Linux: `apt/dnf/pacman`).
6072

61-
### System Dependencies**Verify Tools:** Checks if `yt-dlp`, `ffmpeg`, `ffprobe`, and `mp3gain` are installed and accessible.
62-
**Check & Install System Deps:** Attempts automatic installation (Windows: `winget`; macOS: `brew`; Linux: `apt/dnf/pacman`).
73+
### Controls & Log
74+
- **Run/Cancel:** Starts or stops the current process.
75+
- **Progress Bar:** Shows the progress of downloads and the joining process.
76+
- **Log Window:** Displays detailed real-time information about the ongoing process. Right-click to copy or clear the log.
6377

64-
### Controls & Log**Run/Cancel:** Starts or stops the current process.
65-
**Progress Bar:** Shows determinate progress during downloads and joining.
66-
**Log Window:** Displays detailed information about the ongoing process. Right-click to copy or clear the log.
78+
## Troubleshooting
6779

68-
## Troubleshooting### Tool Not Found (ffmpeg, mp3gain)If the log reports a tool is "missing" even after you've installed it, try restarting the application so PATH changes are picked up.
80+
### Tool Not Found Errors
81+
If the log reports that a tool like `ffmpeg` or `mp3gain` is "missing" even after you have installed it, your system may not be aware of its location. **Try restarting the application** or your computer to ensure the updated system PATH is recognized.
6982

70-
### Downloads are Slow or FailingTry increasing the **Delay between items** to 5 seconds or more. Check your internet connection. The video may have been removed or be region-locked.
83+
### Downloads are Slow or Failing
84+
- **Rate Limiting:** Try increasing the **Delay between items** to 5 seconds or more.
85+
- **Connection Issues:** Check your internet connection.
86+
- **Content Availability:** The video may have been removed or be restricted in your region.
7187

72-
### Private/Members-Only Videos Not WorkingThis 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.
88+
### Private/Members-Only Videos Not Working
89+
This is almost always a cookie issue.
90+
1. Ensure you are logged into YouTube in your browser.
91+
2. Use a browser extension like **"Cookie-Editor"** to export your YouTube cookies to a `.json` file.
92+
3. In the app, select that `.json` file in the "Cookies file" field and try again.

0 commit comments

Comments
 (0)