Build a YouTube Downloader CLI | Merge Video/Audio | Fix Noise

Short summary: This writeup collects the practical problems I hit while building a lightweight Node.js CLI downloader and the concrete solutions I used. It’s intended as a hands-on guide you can copy into your project: detecting formats, downloading video-only + audio-only, merging with ffmpeg, why merged audio can sound noisy, and how to clean it. At the end I add a short note about a ready tool that implements these ideas.

---

1. Problem overview: what actually goes wrong (and why you should care)

When you try to download YouTube content at a specific quality you want, you’ll immediately encounter a few recurring issues:

• Choosing quality does not always give the expected result. Many combined (audio+video) formats are only available at low resolutions (e.g., 360p). Higher resolutions are offered as separate streams (video-only + audio-only). If your downloader blindly picks “the best combined format”, you end up with 360p even when 1080p is available as video-only.
• Merging separate streams is required if you want higher resolution video + audio. That means download two streams and run an external tool like ffmpeg to compose them.
• Post-merge audio quality can degrade. After merging, some outputs exhibit background noise/hiss or other artifacts. This is surprising because you downloaded the original audio stream — the merging/processing step introduced or exposed artifacts.
• Cross-platform packaging and dependencies. Bundling or requiring ffmpeg across Windows/macOS/Linux has pitfalls unless you handle binaries carefully.
• Playlists, rate limits and UX. Handling playlists, retries and user feedback (progress bars) requires additional design.

If you or your team plan to build a downloader, solving these correctly makes the difference between a toy and a reliable tool.

---

2. Strategy & architecture (high level)

1. Enumerate formats for a URL (video-only, audio-only, combined).
2. Decide: if user requested resolution is available as combined format → download combined; otherwise download video-only + audio-only.
3. Download streams concurrently (with retries, backoff, and progress tracking).
4. Merge using ffmpeg. Prefer stream copy when possible (-c copy) to avoid re-encoding, but re-encode if you must normalize or filter audio.
5. Post-process audio with a light noise-reduction filter if artifacts are present.
6. Provide a good UX: interactive mode and flags, progress bars, verbose logs for debugging.
7. Bundle or locate ffmpeg reliably (e.g., ffmpeg-static or provide clear instructions).

---

3. Practical code snippets & notes

3.1 — Detect available formats with ytdl-core (Node.js)

// Example: list formats and pick best video-only + audio-only
const ytdl = require('ytdl-core');

async function listFormats(url) {
  const info = await ytdl.getInfo(url);
  const formats = info.formats;

  const videoOnly = formats.filter(f => f.hasVideo && !f.hasAudio)
                           .sort((a,b) => (b.height || 0) - (a.height || 0));
  const audioOnly = formats.filter(f => f.hasAudio && !f.hasVideo)
                           .sort((a,b) => (b.audioBitrate || 0) - (a.audioBitrate || 0));
  const combined = formats.filter(f => f.hasVideo && f.hasAudio)
                          .sort((a,b) => (b.qualityLabel || '').localeCompare(a.qualityLabel || ''));

  return { videoOnly, audioOnly, combined };
}

Tip: show these options to the user and allow explicit selection (or implement “smart selection” that picks the best available combination).

---

3.2 — Downloading streams (concurrent with progress)

Use streaming writes and a progress library (e.g., cli-progress) so the user sees download progress:

const fs = require('fs');
const ytdl = require('ytdl-core');

function downloadFormat(url, format, outputPath) {
  return new Promise((resolve, reject) => {
    const stream = ytdl(url, { format });
    stream.pipe(fs.createWriteStream(outputPath));
    stream.on('progress', (chunkLength, downloaded, total) => {
      // update progress bar
    });
    stream.on('end', () => resolve());
    stream.on('error', err => reject(err));
  });
}

Retries: wrap downloads with retry/backoff to handle transient network or YouTube throttling issues.

---

3.3 — Merge with FFmpeg (basic merge, copy streams)

When formats are compatible (same container/codecs), prefer -c copy.

ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

When to re-encode: if audio codec/container mismatch or you want to apply filters, you must re-encode:

ffmpeg -i video.mp4 -i audio.m4a -c:v copy -c:a aac -b:a 192k merged.mp4

Note: re-encoding audio may slightly change the quality; choose sensible defaults (AAC 128–192 kbps or keep original bitrate if possible).

---

3.4 — The audio noise problem and solutions

Symptom: merged audio has extra background noise / hiss that wasn’t obvious in the original stream.

Possible causes:

• Mismatch in sample rates or codecs requiring ffmpeg to resample/re-encode.
• Bad muxing path when using copy and then later rewrapping.
• Inadvertent transforms (volume normalization, resampling) when using filters or wrong flags.
• Source streams themselves may be compressed with artifacts that become more noticeable after merging.

Practical fixes:

1. Prefer native ffmpeg denoisers if artifacts are present. Example:

# afftdn: frequency-domain denoiser
ffmpeg -i merged.mp4 -af "afftdn=nf=-25" final_clean.mp4

1. Highpass/lowpass to remove low-frequency rumble:

ffmpeg -i merged.mp4 -af "highpass=f=70, lowpass=f=12000" final_clean.mp4

1. Custom filters / internal filter If you have a custom filter or tuned profile (for me, named mp.rnnn internally), run it as an -af parameter:

ffmpeg -i merged.mp4 -af "mp.rnnn" final_clean.mp4

Advice: start with afftdn and simple highpass/lowpass. Only add complex or proprietary filters after testing. Always keep the original audio saved so you can A/B test.

1. Ensure consistent sampling Force a sample rate to avoid hidden resampling artifacts:

ffmpeg -i merged.mp4 -ar 48000 -ac 2 -af "afftdn=nf=-25" final_clean.mp4

1. Automate detection + conditional filtering Run a quick audio quality check (e.g., compute RMS or detect noise floor) and apply the filter conditionally when noise passes a threshold.

---

4. Playlist handling & ranges

• List extraction: get playlist video IDs, then loop over them with pagination.
• Range downloads: accept "start-end" strings and map them to indices.
• Concurrency limits: for large playlists, download in small batches (e.g., 3 concurrent downloads) to avoid bandwidth spikes or hitting YouTube rate limits.
• Resume support: keep partial files and resume if possible (ytdl supports range requests in many cases).

---

5. Packaging ffmpeg & cross-platform considerations

• Use ffmpeg-static as a convenient bundled binary for most platforms. It simplifies CI and end-user installs.
• If you need full control or want smaller distribution, document how to install a system ffmpeg and allow an environment variable override (e.g., FFMPEG_PATH).
• Watch license: ffmpeg has LGPL/GPL components depending on build; pick builds accordingly and document licenses.

---

6. UX & CLI tips

• Interactive mode for beginners: prompt for URL, quality, format.
• Flags for automation: --url, --type, --quality, --output, --no-progress, --verbose.
• Verbose logs: include format selection details (which format IDs you picked and why). This is invaluable for debugging format/quality issues.
• Progress bars: show per-stream progress and an overall task progress for playlists.
• Exit codes: make exit codes meaningful (network error, ffmpeg error, invalid URL, permission denied).

---

7. Testing & validation

• A/B test: compare original audio stream and final audio after merge + filter. Keep both and allow quick playback.
• Sample videos: maintain a test set containing different encodings/resolutions (360p combined, 720p+audio separate, DASH formats).
• Automated CI: run unit tests on format selection logic and integration tests for small merges. For ffmpeg steps, you can run smoke checks (exists file, duration matches input within small delta).

---

8. Troubleshooting checklist (quick)

• If the downloader keeps giving 360p:

  • Inspect available formats (ytdl-core info) and look for video-only formats at desired resolution.

• If merge fails:

  • Check ffmpeg stdout, container/codec mismatches, and try re-encoding instead of -c copy.

• If audio noisy after merge:

  • Try afftdn, highpass/lowpass; check sample rates and re-encode audio to a stable sample rate (e.g., 48k).

• If downloads slow or fail intermittently:

  • Implement retries with exponential backoff; reduce concurrency.

---

9. Example end-to-end shell flow (what the tool automates)

# download best video-only at requested resolution
ytdl 'https://youtube.com/watch?v=ID' --format videoonly -o video.mp4

# download best audio-only
ytdl 'https://youtube.com/watch?v=ID' --format audioonly -o audio.m4a

# merge (prefer copy if compatible)
ffmpeg -i video.mp4 -i audio.m4a -c:v copy -c:a copy merged.mp4

# if artifacts exist -> filter audio
ffmpeg -i merged.mp4 -af "afftdn=nf=-25" final_clean.mp4

---

11. Small section: about my ready tool that i built

If you’d rather try a ready implementation of the above ideas, I created a small CLI called Downtube that automates the workflow described here: format detection, video-only + audio-only downloading, ffmpeg merging, and an optional noise-filter step. It also supports playlists, range downloads, progress indicators, and a simple interactive CLI.

Try it / see source:
https://github.com/ahegazy0/downtube

---