YouTube Audio Downloader Free
Pricing
Pay per usage
Downloads audio from YouTube videos and stores them as files in the key-value store with metadata in the dataset.
Pricing
Pay per usage
Rating
2.3
(2)
Developer
Epic Scrapers
Maintained by CommunityActor stats
2
Bookmarked
177
Total users
49
Monthly active users
a few seconds ago
Last modified
Categories
Share
# YouTube Audio Downloader for Apify## Build: docker build -t youtube-audio-downloader .# Run: docker run -p 8000:8000 youtube-audio-downloader
FROM apify/actor-node:24
USER root
# Install ffmpeg and Python3 (needed for yt-dlp binary)RUN apk add --no-cache ffmpeg python3
# Copy package files and install Node dependencies (as root to avoid EACCES)COPY package*.json ./RUN npm --quiet set progress=false \ && npm install --omit=dev --omit=optional \ && echo "Installed NPM packages:" \ && (npm list --omit=dev --all || true) \ && echo "Node.js version:" \ && node --version \ && echo "NPM version:" \ && npm --version \ && rm -r ~/.npm
USER myuser
# Copy application codeCOPY . ./
CMD ["node", "src/main.js"]min-release-age=1root = true
[*]indent_style = spaceindent_size = 4charset = utf-8trim_trailing_whitespace = trueinsert_final_newline = trueend_of_line = lfquote_type = single1# SEO Deconstruction: YouTube Audio Downloader on Apify Store2
3## Top-Ranking Competitors on Apify Store4
5### 1. streamers/youtube-video-downloader6- **URL**: apify.com/streamers/youtube-video-downloader7- **Rating**: 3.8 ⭐ (23 reviews)8- **Total users**: 12K9- **Monthly active**: 40210- **Price**: $2.50 / 1,000 video downloads of 1 MB11- **Why it ranks #1**: Apify-maintained actor, huge user base (12K total users), strong brand "Streamers", highest engagement metrics. The Apify "maintained by Apify" badge is a trust signal.12- **SEO signals**: Title "YouTube Video Downloader" is highly searchable. Broad format support (MP4, MP3, AVI). Multiple cloud storage integrations. Comprehensive FAQ section. Strong API documentation with multiple language examples.13
14### 2. tazy/youtube-converter15- **URL**: apify.com/tazy/youtube-converter16- **Rating**: 0.0 (0 reviews)17- **Total users**: 7718- **Price**: $50.00 / 1,000 results19- **Why it ranks**: Clean, focused README. Strong emphasis on cookies/authentication for age-restricted content. Health-check mode for Apify Store compatibility. Simple, direct messaging.20- **SEO signals**: Uses both "YouTube Converter" and "MP4/MP3" in title. Detailed cookie export instructions (keyword-rich). Structured with emoji headers.21
22### 3. epicscrapers/youtube-audio-downloader23- **URL**: apify.com/epicscrapers/youtube-audio-downloader24- **Rating**: Not visible (likely new)25- **Why it ranks**: Direct name match for "youtube audio downloader". Smart proxy tiering concept. Anti-block technical detail. Competitive pricing positioning.26- **SEO signals**: "YouTube Audio Downloader" exact match. Technical depth attracts developers. Comparison with residential vs datacenter proxy costs.27
28### 4. scrapearchitect/youtube-audio-mp3-downloader29- **URL**: apify.com/scrapearchitect/youtube-audio-mp3-downloader30- **Why it ranks**: Multi-language audio track extraction (unique differentiator). YouTube Kids support. Heavy emoji usage in title/headers for visual appeal.31- **SEO signals**: Covers "YouTube Audio/MP3 Downloader", "YouTube Kids", "Multi-Language Audio". Extremely long-form content. Related tools section for internal linking.32
33### 5. lurkapi/youtube-to-mp3-audio-downloader34- **URL**: apify.com/lurkapi/youtube-to-mp3-audio-downloader35- **Total users**: 22536- **Monthly active**: 8137- **Price**: $2.00 / 1,000 minutes downloaded38- **Why it ranks**: Low price point. Excellent technical documentation. Multiple format support (8 formats). Clear pricing model (per-minute). "Permanent download links" differentiator.39- **SEO signals**: Title "YouTube to MP3 Audio Downloader API". Rich FAQ with format advice. Detailed bitrate recommendations. Keywords in footer.40
41### 6. codenest/youtube-mp3-audio-downloader42- **URL**: apify.com/codenest/youtube-mp3-audio-downloader43- **Why it ranks**: Part of a large suite of related actors (internal linking network). Heavy emoji use. Multiple format/bitrate options.44- **SEO signals**: "YouTube MP3/Audio Downloader" title. Massive related-actors section for internal links. Use-case focused content.45
46## Common Ranking Factors47
481. **Exact-match titles** — "YouTube Audio Downloader", "YouTube to MP3", "YouTube MP3 Downloader" rank for those queries492. **Emoji in headers** — Visual appeal increases click-through from search results503. **Long-form content** — More text = more keyword density and topical authority514. **Pricing prominence** — Users compare prices; clear pricing = lower bounce rate525. **Technical depth** — Developer audience wants to understand how it works536. **API documentation** — Many users integrate via API; API docs = higher engagement547. **Related tools linking** — Internal linking across actor suite boosts SEO558. **Apify-maintained badge** — Trust signal that improves CTR56
57## Our SEO Opportunity58
59Our actor is named `youtube-audio-downloader` — exact match for a high-volume keyword. Key differentiators to emphasize:60
611. **Smart proxy tiering** — datacenter → residential fallback saves money (unique feature)622. **CDN-split architecture** — proxy only for metadata, direct CDN download for audio (cost-saving)633. **Auto-updating yt-dlp** — stays ahead of YouTube changes (reliability)644. **Firefox cookies** — works where Chrome cookies fail (Chrome 127+ issue)655. **Format range** — MP3, M4A, Opus, FLAC, WAV, best (wider than most competitors)666. **Metadata embedding** — ID3 tags with title, artist (polish feature)677. **Random delay + user agent rotation** — anti-block by design# configurations.idea.vscode.zed
# crawlee and apify storage foldersapify_storagecrawlee_storagestorage
# installed filesnode_modules
# git folder.git# This file tells Git which files shouldn't be added to source control
.DS_Store.idea.vscode.zednode_modulesstorage
# Added by Apify CLI.venv{ "name": "youtube-audio-downloader", "version": "0.0.1", "type": "module", "description": "Downloads audio from YouTube videos and stores them as files in the key-value store with metadata in the dataset.", "engines": { "node": ">=18.0.0" }, "dependencies": { "apify": "^3.7.0" }, "devDependencies": { "@apify/eslint-config": "^2.0.0", "eslint": "^9.29.0", "eslint-config-prettier": "^10.1.5", "prettier": "^3.5.3", "vitest": "^4.1.0" }, "scripts": { "start": "node ./src/main.js", "format": "prettier --write .", "format:check": "prettier --check .", "lint": "eslint", "lint:fix": "eslint --fix", "test": "vitest run" }, "author": "It's not you it's me", "license": "ISC"}{ "printWidth": 120, "tabWidth": 4, "singleQuote": true}1# YouTube Audio Downloader — Agent Guidelines2
3## Project Identity4
5An Apify Actor that downloads audio from YouTube videos. Downloads through YouTube CDN (free), uses residential proxies only for metadata extraction (lightweight). Converts audio with ffmpeg, embeds metadata, and stores results in an Apify key-value store with dataset records.6
7**Tech stack:** Node 24+ (ESM), Apify SDK 3.x, yt-dlp (auto-downloaded at runtime), ffmpeg, Docker (Alpine), Vitest, ESLint, Prettier.8
9## Architecture Overview10
11```12Input (videoUrls, format, bitrate, etc.)13 │14 ▼15yt-dlp extract-info ──→ residential proxy ──→ JSON metadata (video title, CDN URL, etc.)16 │17 ▼18fetch audio from YouTube CDN (free, no proxy) ──→ raw .m4a file19 │ │20 ▼ ▼21ffmpeg convert (if needed) keep as-is (opus/best)22 │23 ▼24ffmpeg embed metadata (title, artist)25 │26 ▼27Actor.setValue(kv store) + Actor.pushData(dataset item)28```29
30**Key design decisions:**31- **Proxy-split:** metadata goes through residential proxy (~5KB), audio downloads go direct to YouTube CDN. This saves ~99.9% residential proxy bandwidth.32- **No datacenter proxy fallback:** YouTube blocks datacenter IPs for API calls, so the code goes straight to residential. (README.md mentions a datacenter→residential tiering, but the actual `main.js` only uses residential.)33- **No iOS player client:** `youtube:player_client=web,mweb,android` — the iOS client silently drops cookies.34- **yt-dlp is not bundled:** downloaded fresh each run from GitHub releases. This keeps the actor up to date with YouTube's extractor changes, but means builds are stale and the binary is fetched at container startup.35
36## Key Files37
38| File | Purpose |39|---|---|40| `src/main.js` | Main actor logic: input parsing, proxy setup, yt-dlp subprocess, ffmpeg conversion, KV store upload |41| `src/utils.js` | Helpers: `safeFilename()`, `mimeType()`, `formatDuration()`, `formatBytes()` |42| `test/main.test.js` | Vitest unit tests (only covers utils, not the actor itself) |43| `.actor/actor.json` | Apify actor definition (name, title, spec version) |44| `.actor/input_schema.json` | Apify input UI schema (videoUrls, format, bitrate, proxy, cookies, etc.) |45| `Dockerfile` | Alpine-based build with ffmpeg + python3 (for yt-dlp at runtime) |46| `.github/workflows/test.yaml` | CI: runs `npm test` on PR/push to main |47| `package.json` | Scripts: `start`, `test`, `format`, `lint` |4849## Development Workflows50
51```bash52# Install dependencies53npm install54
55# Run tests56npm test57
58# Lint59npm run lint60
61# Format62npm run format63
64# Run locally (requires ffmpeg on PATH and a running apify proxy tunnel)65node src/main.js66```67
68## Agent Guidelines69
70### When asked about the project71- This is an Apify Actor, not a general-purpose YouTube downloader. It uses Apify's proxy (RESIDENTIAL group) and KV store.72- The README.md is the primary user-facing documentation and should be kept in sync with `src/main.js` behavior.73
74### When making changes751. **Read the full `src/main.js` first.** The proxy logic, yt-dlp subprocess management, and error handling are tightly coupled.762. **Keep proxy costs in mind.** The whole architecture is designed to minimize residential proxy bandwidth. Don't add operations that route large downloads through the proxy.773. **Don't bundle yt-dlp.** It's downloaded at runtime intentionally (auto-updates). If you need to pin a version, add a fallback URL or version parameter, don't bake it into the Docker image.784. **Respect the heartbeat loop (`withHeartbeat()`).** Any long-running operation (metadata fetch, CDN download, ffmpeg conversion) should use it so Apify doesn't kill the actor for being unresponsive.795. **Don't use the iOS player client.** It silently drops cookies. Stick to `web,mweb,android`.80
81### Proxy strategy82- The actor always uses Apify `RESIDENTIAL` proxies — it doesn't attempt datacenter first (the README.md describes a two-tier strategy, but the code was simplified to go straight to residential).83- Each URL gets a new proxy session (`session_<random hex>`).84- Proxy country defaults to `US`, configurable via input.85
86### Docker build quirks87- `npm install` runs as root before switching to `myuser`. Make sure any `COPY` after `USER myuser` uses `--chown=myuser:myuser`.88- `python3` is installed in the base image because yt-dlp needs it for post-processing.89- The `.dockerignore` excludes `node_modules`, `storage`, and IDE configs.90
91### Known issues92- **yt-dlp status/progress output is suppressed** (uses `--quiet`). The only feedback during a download is the heartbeat log line. See `.pi/todos/f2a2936e.md` for tracking this.93- **CDN download fallback is fragile** — if the direct `fetch()` to YouTube CDN fails, it falls back to a full yt-dlp download through the residential proxy (expensive).94- **Thumbnail embedding is disabled** in the metadata step — the code only embeds text metadata (title, artist) for MP3.95- **No local test coverage for the yt-dlp integration.** The unit tests only cover `utils.js`. Full integration testing requires an Apify token or a mock.96
97### When debugging failures98- Check whether yt-dlp was successfully downloaded at startup (the version log line).99- Check whether the proxy session is valid (residential proxy URL may be stale).100- YouTube CDN URLs from `info.url` are time-limited — the download must happen quickly after `extractInfo()`.101- If a video is age-restricted, the user must provide Firefox cookies. Chrome cookies since v127 can't be exported.1import prettier from 'eslint-config-prettier';2
3import apify from '@apify/eslint-config/js.js';4
5// eslint-disable-next-line import-x/no-default-export6export default [{ ignores: ['**/dist'] }, ...apify, prettier];{ "title": "YouTube Audio Downloader — Input", "description": "Download audio from YouTube videos with smart proxy tiering, format conversion, and metadata embedding.", "type": "object", "schemaVersion": 1, "properties": { "videoUrls": { "title": "YouTube Video URLs", "type": "array", "description": "One or more YouTube video URLs to download audio from.", "editor": "stringList", "prefill": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "minItems": 1, "uniqueItems": true }, "audioFormat": { "title": "Audio Format", "type": "string", "description": "Output audio format. M4A and Opus/WebM usually download directly without conversion; MP3, FLAC, and WAV require ffmpeg conversion.", "default": "m4a", "editor": "select", "enum": ["mp3", "m4a", "opus", "flac", "wav", "best"], "enumTitles": [ "MP3 (converted, maximum compatibility)", "M4A (AAC, better quality/size, Apple devices)", "Opus (best quality-to-size, podcasts)", "FLAC (lossless, archival)", "WAV (uncompressed, editing)", "Best (original format, no conversion)" ] }, "audioBitrate": { "title": "Audio Bitrate", "type": "string", "description": "Bitrate for lossy formats. Ignored for FLAC, WAV, and 'best'.", "default": "192", "editor": "select", "enum": ["128", "192", "256", "320"], "enumTitles": ["128 kbps", "192 kbps", "256 kbps", "320 kbps"] }, "embedMetadata": { "title": "Embed Metadata", "type": "boolean", "description": "Embed title, artist, and thumbnail as audio tags (ID3 for MP3, etc.).", "default": true, "editor": "checkbox" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Leave as-is to use default datacenter proxies (cheap). Escalates to residential automatically if YouTube blocks datacenter IPs.", "default": { "useApifyProxy": true, "apifyProxyGroups": [], "apifyProxyCountry": "US" }, "prefill": { "useApifyProxy": true, "apifyProxyGroups": [], "apifyProxyCountry": "US" }, "editor": "proxy" }, "cookies": { "title": "Cookies (optional)", "type": "string", "description": "Paste Firefox cookies.txt content here for age-restricted videos. Chrome cookies since v127 use app-bound encryption and cannot be read externally. Use Firefox's cookies.sqlite — see docs for extraction script.", "editor": "textarea", "default": "" }, "allowProxyMediaDownload": { "title": "Allow Proxy Media Download Fallback", "type": "boolean", "description": "If enabled, the actor may download the full audio through residential proxy when direct CDN download fails. This can be expensive and is disabled by default.", "default": false, "editor": "checkbox" }, "sleepBetweenUrls": { "title": "Delay Between URLs (seconds)", "type": "integer", "description": "Random delay range max between processing videos. Min is always 5s. Increase if getting blocked.", "default": 12, "minimum": 5, "maximum": 120 } }, "required": ["videoUrls"]}{ "actorSpecification": 1, "$schema": "https://apify.com/schemas/v1/actor.ide.json", "name": "youtube-audio-downloader", "title": "YouTube Audio Downloader", "description": "Downloads audio from YouTube videos and stores them as files in the key-value store with metadata in the dataset.", "version": "0.0", "buildTag": "latest", "meta": { "templateId": "js-empty", "generatedBy": "Claude Code with Claude Sonnet 4.5" }}1import { describe, expect, it } from 'vitest';2import { safeFilename, mimeType } from '../src/utils.js';3
4describe('safeFilename', () => {5 it('removes special characters', () => {6 expect(safeFilename('Rick Astley - Never Gonna Give You Up (Official)')).toBe(7 'Rick_Astley_-_Never_Gonna_Give_You_Up_Official',8 );9 });10
11 it('truncates to 100 chars', () => {12 const long = 'a'.repeat(200);13 expect(safeFilename(long).length).toBe(100);14 });15
16 it('replaces spaces with underscores', () => {17 expect(safeFilename('hello world')).toBe('hello_world');18 });19});20
21describe('mimeType', () => {22 it('returns correct mime types', () => {23 expect(mimeType('mp3')).toBe('audio/mpeg');24 expect(mimeType('m4a')).toBe('audio/mp4');25 expect(mimeType('flac')).toBe('audio/flac');26 expect(mimeType('wav')).toBe('audio/wav');27 });28
29 it('falls back to application/octet-stream', () => {30 expect(mimeType('unknown')).toBe('application/octet-stream');31 });32});1<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 400" width="1600" height="400">2 <defs>3 <!-- Light subtle gradient -->4 <linearGradient id="bgGrad" x1="0" y1="0" x2="0" y2="1">5 <stop offset="0%" stop-color="#fafafa"/>6 <stop offset="100%" stop-color="#f0f0f0"/>7 </linearGradient>8
9 <!-- Accent color for format badges -->10 <linearGradient id="accentGrad" x1="0" y1="0" x2="1" y2="0">11 <stop offset="0%" stop-color="#cc0000"/>12 <stop offset="100%" stop-color="#e53935"/>13 </linearGradient>14 </defs>15
16 <!-- Background -->17 <rect width="1600" height="400" fill="url(#bgGrad)"/>18
19 <!-- Accent bar at top -->20 <rect x="0" y="0" width="1600" height="4" fill="url(#accentGrad)"/>21
22 <!-- Thin accent line under the title area -->23 <rect x="640" y="175" width="320" height="2" fill="#cc0000" opacity="0.15"/>24
25 <!-- Main title -->26 <text x="800" y="145"27 font-family="'Inter', 'Inter Display', -apple-system, BlinkMacSystemFont, sans-serif"28 font-size="52"29 font-weight="700"30 letter-spacing="-0.5"31 text-anchor="middle"32 fill="#1a1a1a">33 YouTube Audio Downloader34 </text>35
36 <!-- Tagline -->37 <text x="800" y="215"38 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"39 font-size="18"40 font-weight="400"41 letter-spacing="3.5"42 text-anchor="middle"43 fill="#666666"44 opacity="0.8">45 Extract · Convert · Automate46 </text>47
48 <!-- Format badges -->49 <g transform="translate(800, 295)">50 <text x="-162" y="0"51 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"52 font-size="15"53 font-weight="600"54 text-anchor="middle"55 fill="#999999">56 MP357 </text>58
59 <text x="-110" y="0"60 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"61 font-size="12"62 font-weight="300"63 text-anchor="middle"64 fill="#bbbbbb">//</text>65
66 <text x="-65" y="0"67 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"68 font-size="15"69 font-weight="600"70 text-anchor="middle"71 fill="#999999">72 M4A73 </text>74
75 <text x="-13" y="0"76 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"77 font-size="12"78 font-weight="300"79 text-anchor="middle"80 fill="#bbbbbb">//</text>81
82 <text x="35" y="0"83 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"84 font-size="15"85 font-weight="600"86 text-anchor="middle"87 fill="#999999">88 Opus89 </text>90
91 <text x="90" y="0"92 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"93 font-size="12"94 font-weight="300"95 text-anchor="middle"96 fill="#bbbbbb">//</text>97
98 <text x="133" y="0"99 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"100 font-size="15"101 font-weight="600"102 text-anchor="middle"103 fill="#999999">104 FLAC105 </text>106
107 <text x="185" y="0"108 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"109 font-size="12"110 font-weight="300"111 text-anchor="middle"112 fill="#bbbbbb">//</text>113
114 <text x="226" y="0"115 font-family="'Inter', -apple-system, BlinkMacSystemFont, sans-serif"116 font-size="15"117 font-weight="600"118 text-anchor="middle"119 fill="#999999">120 WAV121 </text>122 </g>123</svg>1/**2 * YouTube Audio Downloader — Apify Actor3 *4 * Downloads audio from YouTube videos using yt-dlp (invoked as a subprocess).5 * Supports format conversion, metadata embedding, proxy tiering (datacenter →6 * residential fallback), and Firefox cookies for age-restricted content.7 */8
9import { Actor } from 'apify';10import { execSync } from 'node:child_process';11import {12 createWriteStream,13 mkdtempSync,14 readFileSync,15 statSync,16 writeFileSync,17 rmSync,18} from 'node:fs';19import { randomBytes } from 'node:crypto';20import { tmpdir } from 'node:os';21import { join, extname } from 'node:path';22import { setTimeout as sleep } from 'node:timers/promises';23import { Writable } from 'node:stream';24import { safeFilename, mimeType, formatDuration, formatBytes } from './utils.js';25
26// ── Heartbeat ──────────────────────────────────────────────────────────────27
28/**29 * Wraps an async operation so a heartbeat message is printed every `intervalMs`30 * while the operation runs. The heartbeat is suppressed once the operation31 * completes (so there's no trailing log after the "Done" message).32 */33async function withHeartbeat(promiseOrFn, msg, { intervalMs = 15_000, abortSignal } = {}) {34 let done = false;35 // Support both sync/async functions and plain promises36 let value;37 try {38 value = typeof promiseOrFn === 'function' ? promiseOrFn() : promiseOrFn;39 } catch (e) {40 return Promise.reject(e);41 }42 // Normalize to a promise43 const promise = Promise.resolve(value);44 const result = promise.then(45 (v) => { done = true; return v; },46 (e) => { done = true; throw e; },47 );48
49 const hb = (async () => {50 let count = 0;51 while (!done) {52 await sleep(intervalMs);53 if (done) break;54 count++;55 const elapsed = count * (intervalMs / 1000);56 console.log(` ${msg} (still working... ${elapsed}s elapsed)`);57 }58 })();59
60 try {61 return await result;62 } finally {63 done = true;64 // brief yield so hb can exit65 await sleep(0);66 }67}68
69// ── Helpers ───────────────────────────────────────────────────────────────70
71const USER_AGENTS = [72 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36',73 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',74 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36',75 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15',76];77
78function randomUserAgent() {79 return USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)];80}81
82function parseCookiesTxt(text) {83 if (!text || !text.trim()) return null;84 const dir = mkdtempSync(join(tmpdir(), 'cookies-'));85 const path = join(dir, 'cookies.txt');86 writeFileSync(path, text);87 return path;88}89
90// Lazy-init yt-dlp binary — download the latest at startup91let ytDlpPath = null;92
93async function ensureYtDlp() {94 if (ytDlpPath) return;95 const dir = mkdtempSync(join(tmpdir(), 'ytdlp-bin-'));96 ytDlpPath = join(dir, 'yt-dlp');97 console.log(' Downloading latest yt-dlp...');98 const resp = await fetch('https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp');99 if (!resp.ok) throw new Error(`Failed to download yt-dlp: HTTP ${resp.status}`);100 const buffer = Buffer.from(await resp.arrayBuffer());101 writeFileSync(ytDlpPath, buffer, { mode: 0o755 });102 const ver = execSync(`${ytDlpPath} --version`, { encoding: 'utf-8' }).trim();103 console.log(` yt-dlp ${ver} ready (${formatBytes(buffer.length)})`);104}105
106/**107 * Run yt-dlp and return stdout as a string.108 */109function ytdlp(args, { maxBuffer = 10 * 1024 * 1024, timeout = 120_000 } = {}) {110 const quoted = args.map((a) => `"${a.replace(/"/g, '\\"')}"`).join(' ');111 return execSync(`"${ytDlpPath}" ${quoted}`, {112 maxBuffer,113 timeout,114 encoding: 'utf-8',115 shell: true,116 }).trim();117}118
119// ── yt-dlp operations ─────────────────────────────────────────────────────120
121/**122 * Extract JSON metadata from a YouTube URL without downloading.123 */124function extractInfo(url, { proxyUrl, cookiesPath, playerClients = 'tv_embedded,tv,web,mweb,android' }) {125 const tmpDir = mkdtempSync(join(tmpdir(), 'ytdlp-'));126 try {127 const args = [128 url,129 '--no-playlist',130 '--quiet',131 '--no-warnings',132 '--print-json',133 '--skip-download',134 '--user-agent', randomUserAgent(),135 '--socket-timeout', '30',136 '--retries', '0',137 '--fragment-retries', '0',138 '--extractor-retries', '0',139 '--sleep-requests', '1',140 '--xff', 'default',141 '--extractor-args', `youtube:player_client=${playerClients};skip=hls`,142 '--output', join(tmpDir, '%(title)s.%(ext)s'),143 ];144 if (proxyUrl) args.push('--proxy', proxyUrl);145 if (cookiesPath) args.push('--cookies', cookiesPath);146
147 const stdout = ytdlp(args, { maxBuffer: 10 * 1024 * 1024, timeout: 120_000 });148 // yt-dlp may output multiple JSON lines; take the last one (the video info)149 const lines = stdout.split('\n').filter(Boolean);150 const info = JSON.parse(lines[lines.length - 1]);151 const title = info.title || 'Unknown';152 const dur = info.duration || 0;153 console.log(` Found: "${title}" — ${formatDuration(dur)}`);154 return info;155 } finally {156 try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}157 }158}159
160// ── Stream utils ───────────────────────────────────────────────────────────161
162/**163 * Pipe a web ReadableStream to a file. Works on Node 18+.164 */165async function streamToFile(readableStream, filePath) {166 const fileStream = createWriteStream(filePath);167 const writableStream = Writable.toWeb(fileStream);168 await readableStream.pipeTo(writableStream);169}170
171function bestByBitrate(formats) {172 return formats173 .filter(Boolean)174 .sort((a, b) => (b.abr || b.tbr || 0) - (a.abr || a.tbr || 0))[0] || null;175}176
177function isDirectAudioFormat(format) {178 return format?.url179 && format.vcodec === 'none'180 && format.acodec181 && format.acodec !== 'none'182 && ['http', 'https'].includes(format.protocol || 'https');183}184
185function hasDirectAudioFormats(info) {186 return (info.formats || []).some(isDirectAudioFormat) || isDirectAudioFormat(info);187}188
189function selectAudioFormat(info, requestedFormat) {190 const audioFormats = (info.formats || []).filter(isDirectAudioFormat);191 if (!audioFormats.length && isDirectAudioFormat(info)) return info;192 if (!audioFormats.length) throw new Error('No direct audio-only formats found');193
194 if (requestedFormat === 'm4a') {195 return bestByBitrate(audioFormats.filter((f) => f.ext === 'm4a')) || bestByBitrate(audioFormats);196 }197
198 if (requestedFormat === 'opus' || requestedFormat === 'webm') {199 return bestByBitrate(audioFormats.filter((f) => f.ext === 'webm' || f.acodec?.includes('opus')))200 || bestByBitrate(audioFormats);201 }202
203 return bestByBitrate(audioFormats);204}205
206function mergedHeaders(info, format) {207 return {208 ...(info.http_headers || {}),209 ...(format.http_headers || {}),210 'User-Agent': format.http_headers?.['User-Agent'] || info.http_headers?.['User-Agent'] || randomUserAgent(),211 };212}213
214function ffmpegAudioArgs(audioFormat, audioBitrate) {215 if (audioFormat === 'mp3') return `-c:a libmp3lame -b:a ${audioBitrate}k`;216 if (audioFormat === 'm4a') return `-c:a aac -b:a ${audioBitrate}k`;217 if (audioFormat === 'flac') return '-c:a flac';218 if (audioFormat === 'wav') return '-c:a pcm_s16le';219 return '-c:a copy';220}221
222// ── Main Actor Logic ───────────────────────────────────────────────────────223
224await Actor.init();225
226Actor.on('aborting', async () => {227 await sleep(1000);228 await Actor.exit();229});230
231await ensureYtDlp();232
233const input = (await Actor.getInput()) || {};234const videoUrls = input.videoUrls || [];235const audioFormat = input.audioFormat || 'm4a';236const audioBitrate = input.audioBitrate || '192';237const embedMetadata = input.embedMetadata !== false;238const sleepMax = input.sleepBetweenUrls || 12;239const cookiesText = input.cookies || '';240const proxyInput = input.proxyConfiguration || {};241const useApifyProxy = proxyInput.useApifyProxy !== false;242const proxyCountry = proxyInput.apifyProxyCountry || 'US';243const allowProxyMediaDownload = input.allowProxyMediaDownload === true;244
245if (!videoUrls.length) {246 console.log('No video URLs provided.');247 await Actor.exit();248 process.exit(0);249}250
251console.log(`Processing ${videoUrls.length} video(s), format=${audioFormat}, bitrate=${audioBitrate}k, embed=${embedMetadata}`);252
253// Parse cookies254let cookiesPath = null;255if (cookiesText) {256 cookiesPath = parseCookiesTxt(cookiesText);257 console.log('Cookies loaded from input');258}259
260const conversionFormats = ['mp3', 'm4a', 'flac', 'wav'];261const kvStoreId = process.env.APIFY_DEFAULT_KEY_VALUE_STORE_ID;262const kvBaseUrl = kvStoreId263 ? `https://api.apify.com/v2/key-value-stores/${kvStoreId}/records`264 : null;265
266for (let i = 0; i < videoUrls.length; i++) {267 const url = videoUrls[i];268 console.log(`[${i + 1}/${videoUrls.length}] Processing: ${url}`);269
270 const tmpDir = mkdtempSync(join(tmpdir(), 'ytdlp-'));271
272 try {273 // ── Proxy setup ───────────────────────────────────────────274 let proxyUrl = null;275 let proxyTier = 'none';276 // YouTube blocks datacenter IPs for API calls, so go straight to residential277 if (useApifyProxy) {278 console.log(' Setting up residential proxy...');279 const proxyConfig = await Actor.createProxyConfiguration({280 groups: ['RESIDENTIAL'],281 countryCode: proxyCountry,282 });283 if (proxyConfig) {284 proxyUrl = await proxyConfig.newUrl(`session_${randomBytes(4).toString('hex')}`);285 proxyTier = 'residential';286 }287 }288
289 // ── Download ──────────────────────────────────────────────290 // Strategy: extract CDN URL through (expensive) residential proxy,291 // then download the actual audio from YouTube's CDN for free.292 // Only use the proxy for the metadata call (lightweight).293
294 console.log(' Fetching video metadata via proxy...');295 let info = await withHeartbeat(296 () => extractInfo(url, { proxyUrl, cookiesPath }),297 'Fetching video metadata',298 );299 if (!hasDirectAudioFormats(info)) {300 console.log(' No audio-only formats from initial client set; retrying metadata with TV clients...');301 info = await withHeartbeat(302 () => extractInfo(url, { proxyUrl, cookiesPath, playerClients: 'tv_embedded,tv' }),303 'Retrying video metadata',304 );305 }306 const title = info.title || 'Unknown';307 const videoId = info.id || 'unknown';308 const duration = info.duration || 0;309 const channel = info.channel || info.uploader || '';310 const selectedFormat = selectAudioFormat(info, audioFormat);311 const sourceExt = selectedFormat.ext || info.ext || 'm4a';312 const sourceCodec = selectedFormat.acodec || 'unknown';313 const sourceBitrate = selectedFormat.abr || selectedFormat.tbr || null;314 const requestedDirectFormat = audioFormat === 'best'315 || (audioFormat === 'opus' && (sourceExt === 'webm' || sourceCodec.includes('opus')))316 || audioFormat === sourceExt;317 const needsConversion = conversionFormats.includes(audioFormat) && !requestedDirectFormat;318
319 console.log(` Selected audio-only format ${selectedFormat.format_id || 'unknown'} (${sourceExt}, ${sourceCodec}, ${sourceBitrate || '?'} kbps)`);320
321 // Download selected audio-only CDN stream directly, without proxy cost.322 const rawPath = join(tmpDir, `${safeFilename(title)}.raw.${sourceExt}`);323 console.log(' Downloading audio-only stream from CDN (free, no proxy cost)...');324 let proxyMediaUsed = false;325 try {326 await withHeartbeat(327 (async () => {328 const r = await fetch(selectedFormat.url, {329 headers: mergedHeaders(info, selectedFormat),330 signal: AbortSignal.timeout(300_000),331 });332 if (!r.ok) throw new Error(`CDN returned ${r.status}`);333 await streamToFile(r.body, rawPath);334 })(),335 'Downloading from CDN',336 );337 console.log(` Downloaded ${formatBytes(statSync(rawPath).size)} from CDN`);338 } catch (cdErr) {339 if (!allowProxyMediaDownload) {340 throw new Error(`CDN audio download failed (${cdErr.message}). Proxy media fallback is disabled to avoid residential bandwidth costs.`);341 }342 console.log(` CDN download failed (${cdErr.message}), falling back to full yt-dlp via proxy because allowProxyMediaDownload=true...`);343 proxyMediaUsed = true;344 const fetchArgs = [345 url, '--no-playlist', '--quiet', '--no-warnings',346 '--format', selectedFormat.format_id || 'bestaudio/best',347 '--user-agent', randomUserAgent(),348 '--socket-timeout', '30',349 '--output', rawPath,350 ];351 if (proxyUrl) fetchArgs.push('--proxy', proxyUrl);352 if (cookiesPath) fetchArgs.push('--cookies', cookiesPath);353 ytdlp(fetchArgs, { maxBuffer: 50 * 1024 * 1024, timeout: 600_000 });354 }355
356 // Determine final audio path. Avoid conversion whenever selected source already matches requested output.357 let audioPath;358 let wasConverted = false;359 if (needsConversion) {360 audioPath = join(tmpDir, `${safeFilename(title)}.${audioFormat}`);361 console.log(` Converting to ${audioFormat} with ffmpeg...`);362 execSync(363 `ffmpeg -y -i "${rawPath}" -vn ${ffmpegAudioArgs(audioFormat, audioBitrate)} "${audioPath}"`,364 { stdio: ['ignore', 'pipe', 'pipe'], timeout: 300_000 },365 );366 wasConverted = true;367 console.log(` Converted: ${formatBytes(statSync(audioPath).size)}`);368 } else {369 audioPath = join(tmpDir, `${safeFilename(title)}.${audioFormat === 'opus' ? 'webm' : sourceExt}`);370 execSync(`mv "${rawPath}" "${audioPath}"`);371 }372
373 if (embedMetadata && audioFormat !== 'wav') {374 console.log(' Embedding metadata...');375 try {376 const safeTitle = (info.title || '').replace(/"/g, '\\"');377 const safeArtist = (channel || '').replace(/"/g, '\\"');378 const tmpAudio = `${audioPath}.tmp.${extname(audioPath).replace(/^\./, '')}`;379 execSync(380 `ffmpeg -y -i "${audioPath}" -c copy ` +381 `-metadata title="${safeTitle}" ` +382 `-metadata artist="${safeArtist}" ` +383 `-id3v2_version 3 "${tmpAudio}" && mv "${tmpAudio}" "${audioPath}"`,384 { stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 },385 );386 } catch (metaErr) {387 console.log(` Metadata embedding skipped (${metaErr.message})`);388 }389 }390
391 // ── Store results ─────────────────────────────────────────392 const audioFile = readFileSync(audioPath);393 const fileExt = extname(audioPath).replace(/^\./, '');394 const kvKey = `audio-${videoId}`;395 const contentType = mimeType(fileExt);396
397 console.log(` Uploading ${formatBytes(audioFile.length)} to key-value store...`);398 await Actor.setValue(kvKey, audioFile, { contentType });399 console.log(` ✓ Done: "${title}" (${videoId}), ${formatDuration(duration)}, ${formatBytes(audioFile.length)}`);400
401 const item = {402 video_id: videoId,403 video_url: url,404 video_title: title,405 channel,406 duration,407 audio_format: fileExt,408 file_size_bytes: audioFile.length,409 source_format_id: selectedFormat.format_id || null,410 source_ext: sourceExt,411 source_codec: sourceCodec,412 source_bitrate: sourceBitrate,413 was_converted: wasConverted,414 proxy_media_used: proxyMediaUsed,415 kv_store_key: kvKey,416 proxy_tier_used: proxyTier,417 status: 'downloaded',418 };419 if (kvBaseUrl) item.audio_url = `${kvBaseUrl}/${kvKey}`;420 await Actor.pushData(item);421
422 } catch (err) {423 console.error(` ✗ Failed: ${url} — ${err.message}`);424 await Actor.pushData({425 video_url: url,426 status: 'error',427 error: err.message.slice(0, 500),428 });429 } finally {430 try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}431 }432
433 // Random delay between URLs434 if (i < videoUrls.length - 1) {435 const delaySec = 5 + Math.random() * (sleepMax - 5);436 console.log(` Sleeping ${delaySec.toFixed(1)}s before next URL...`);437 await sleep(Math.round(delaySec * 1000));438 }439}440
441console.log('Finished processing all URLs');442await Actor.exit();1/**2 * Utility functions for YouTube Audio Downloader3 */4
5export function safeFilename(title) {6 return title.replace(/[^\w\s-]/g, '').trim().replace(/\s+/g, '_').slice(0, 100);7}8
9const MIME_MAP = {10 mp3: 'audio/mpeg',11 m4a: 'audio/mp4',12 webm: 'audio/webm',13 opus: 'audio/ogg',14 ogg: 'audio/ogg',15 aac: 'audio/aac',16 wav: 'audio/wav',17 flac: 'audio/flac',18};19
20export function mimeType(ext) {21 return MIME_MAP[ext] || 'application/octet-stream';22}23
24/** Format seconds into mm:ss or h:mm:ss */25export function formatDuration(seconds) {26 if (!seconds || seconds <= 0) return '0:00';27 const s = Math.round(seconds);28 const m = Math.floor(s / 60);29 const h = Math.floor(m / 60);30 const sec = s % 60;31 const min = m % 60;32 if (h > 0) return `${h}:${String(min).padStart(2, '0')}:${String(sec).padStart(2, '0')}`;33 return `${min}:${String(sec).padStart(2, '0')}`;34}35
36/** Format bytes into a human-readable string */37export function formatBytes(bytes) {38 if (!bytes || bytes === 0) return '0 B';39 const units = ['B', 'KB', 'MB', 'GB'];40 const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);41 return `${(bytes / Math.pow(1024, i)).toFixed(i === 0 ? 0 : 1)} ${units[i]}`;42}name: CI
on: pull_request: push: branches: [main, master]
jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v6 with: node-version: 24 cache: npm - run: npm ci - run: npm test1{2 "id": "f2a2936e",3 "title": "Add live progress logging during yt-dlp downloads and bust Docker cache for latest yt-dlp",4 "tags": [],5 "status": "open",6 "created_at": "2026-06-21T12:57:24.304Z",7 "assigned_to_session": "019eea31-65b2-7566-b19d-af291511552a"8}9
10- Switch yt-dlp download commands from execSync to spawn with streaming output11- Pipe progress lines (or emit periodic heartbeat logs) so users see something every ~10s12- Bust Docker cache layer for yt-dlp install (use a version tag or curl -O with --time-cond?)