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
5.0
(1)
Developer
Epic Scrapers
Maintained by CommunityActor stats
2
Bookmarked
256
Total users
67
Monthly active users
11 hours
Issues response
21 days 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", "type": "boolean", "description": "Download audio media through residential proxy. Direct CDN downloading is disabled because YouTube often binds media URLs to request fingerprints and returns 403.", "default": true, "editor": "checkbox" }, "continueOnError": { "title": "Continue On Error", "type": "boolean", "description": "If enabled, the Actor run finishes successfully even when one or more videos fail. Failed videos are still pushed to the dataset with status=error.", "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/**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 { execSync } from 'node:child_process';10import { randomBytes } from 'node:crypto';11import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';12import { tmpdir } from 'node:os';13import { extname, join } from 'node:path';14import { setTimeout as sleep } from 'node:timers/promises';15
16import { Actor } from 'apify';17
18import { formatBytes, formatDuration, mimeType, safeFilename } from './utils.js';19
20// ── Heartbeat ──────────────────────────────────────────────────────────────21
22/**23 * Wraps an async operation so a heartbeat message is printed every `intervalMs`24 * while the operation runs. The heartbeat is suppressed once the operation25 * completes (so there's no trailing log after the "Done" message).26 */27async function withHeartbeat(promiseOrFn, msg, { intervalMs = 15_000, abortSignal } = {}) {28 let done = false;29 // Support both sync/async functions and plain promises30 let value;31 try {32 value = typeof promiseOrFn === 'function' ? promiseOrFn() : promiseOrFn;33 } catch (e) {34 return Promise.reject(e);35 }36 // Normalize to a promise37 const promise = Promise.resolve(value);38 const result = promise.then(39 (v) => {40 done = true;41 return v;42 },43 (e) => {44 done = true;45 throw e;46 },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_musllinux');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 = null, useExtractorArgs = false }) {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 '--ignore-no-formats-error',135 '--user-agent',136 randomUserAgent(),137 '--js-runtimes',138 'node',139 '--force-ipv4',140 '--socket-timeout',141 '30',142 '--retries',143 '0',144 '--fragment-retries',145 '0',146 '--extractor-retries',147 '0',148 '--sleep-requests',149 '1',150 '--xff',151 'default',152 '--output',153 join(tmpDir, '%(title)s.%(ext)s'),154 ];155 if (useExtractorArgs && playerClients) args.push('--extractor-args', `youtube:player_client=${playerClients}`);156 if (proxyUrl) args.push('--proxy', proxyUrl);157 if (cookiesPath) args.push('--cookies', cookiesPath);158
159 const stdout = ytdlp(args, { maxBuffer: 10 * 1024 * 1024, timeout: 120_000 });160 // yt-dlp may output multiple JSON lines; take the last one (the video info)161 const lines = stdout.split('\n').filter(Boolean);162 const info = JSON.parse(lines[lines.length - 1]);163 const title = info.title || 'Unknown';164 const dur = info.duration || 0;165 console.log(` Found: "${title}" — ${formatDuration(dur)}`);166 return info;167 } finally {168 try {169 rmSync(tmpDir, { recursive: true, force: true });170 } catch {}171 }172}173
174function assertDownloadedFile(filePath, label) {175 let size = 0;176 try {177 size = statSync(filePath).size;178 } catch {}179 if (size <= 0) throw new Error(`${label} produced an empty file`);180 return size;181}182
183function bestByBitrate(formats) {184 return formats.filter(Boolean).sort((a, b) => (b.abr || b.tbr || 0) - (a.abr || a.tbr || 0))[0] || null;185}186
187function isDirectAudioFormat(format) {188 return (189 format?.url &&190 format.vcodec === 'none' &&191 format.acodec &&192 format.acodec !== 'none' &&193 ['http', 'https'].includes(format.protocol || 'https')194 );195}196
197function hasDirectAudioFormats(info) {198 return (info.formats || []).some(isDirectAudioFormat) || isDirectAudioFormat(info);199}200
201function isTransientProxyError(err) {202 const msg = err?.message || '';203 return /UPSTREAM\d+|Tunnel connection failed|ProxyError|HTTP Error 403|HTTP Error 429|HTTP Error 503|not a bot|confirm you.?re not a bot|Failed to extract any player response|timed out|timeout/i.test(msg);204}205
206async function extractInfoWithProxyRetries(url, options, { freshProxyUrl, label, attempts = 3 }) {207 let lastErr;208 let currentProxyUrl = options.proxyUrl;209 for (let attempt = 1; attempt <= attempts; attempt++) {210 try {211 return await withHeartbeat(212 () => extractInfo(url, { ...options, proxyUrl: currentProxyUrl }),213 attempt === 1 ? label : `${label} (attempt ${attempt}/${attempts})`,214 );215 } catch (err) {216 lastErr = err;217 if (attempt >= attempts || !isTransientProxyError(err)) throw err;218 console.log(` Metadata attempt ${attempt}/${attempts} failed with proxy/network error (${err.message}); retrying with fresh proxy session...`);219 currentProxyUrl = await freshProxyUrl();220 await sleep(1_000 * attempt);221 }222 }223 throw lastErr;224}225
226function selectAudioFormat(info, requestedFormat) {227 const audioFormats = (info.formats || []).filter(isDirectAudioFormat);228 if (!audioFormats.length && isDirectAudioFormat(info)) return info;229 if (!audioFormats.length) throw new Error('No direct audio-only formats found');230
231 if (requestedFormat === 'm4a') {232 return bestByBitrate(audioFormats.filter((f) => f.ext === 'm4a')) || bestByBitrate(audioFormats);233 }234
235 if (requestedFormat === 'opus' || requestedFormat === 'webm') {236 return (237 bestByBitrate(audioFormats.filter((f) => f.ext === 'webm' || f.acodec?.includes('opus'))) ||238 bestByBitrate(audioFormats)239 );240 }241
242 return bestByBitrate(audioFormats);243}244
245function ffmpegAudioArgs(audioFormat, audioBitrate) {246 if (audioFormat === 'mp3') return `-c:a libmp3lame -b:a ${audioBitrate}k`;247 if (audioFormat === 'm4a') return `-c:a aac -b:a ${audioBitrate}k`;248 if (audioFormat === 'flac') return '-c:a flac';249 if (audioFormat === 'wav') return '-c:a pcm_s16le';250 return '-c:a copy';251}252
253function ytdlpAudioFormat(audioFormat) {254 if (audioFormat === 'webm') return 'opus';255 if (audioFormat === 'best') return 'best';256 return audioFormat;257}258
259function downloadAudioWithYtDlp(url, { tmpDir, proxyUrl, cookiesPath, audioFormat, audioBitrate }) {260 const outputBase = `proxy-audio-${randomBytes(4).toString('hex')}`;261 const outputTemplate = join(tmpDir, `${outputBase}.%(ext)s`);262 const args = [263 url,264 '--no-playlist',265 '--quiet',266 '--no-warnings',267 '--format',268 'bestaudio/best',269 '--extract-audio',270 '--audio-format',271 ytdlpAudioFormat(audioFormat),272 '--audio-quality',273 `${audioBitrate}K`,274 '--user-agent',275 randomUserAgent(),276 '--js-runtimes',277 'node',278 '--force-ipv4',279 '--socket-timeout',280 '30',281 '--force-overwrites',282 '--no-part',283 '--output',284 outputTemplate,285 ];286 if (proxyUrl) args.push('--proxy', proxyUrl);287 if (cookiesPath) args.push('--cookies', cookiesPath);288 ytdlp(args, { maxBuffer: 50 * 1024 * 1024, timeout: 600_000 });289
290 const downloaded = readdirSync(tmpDir)291 .filter((name) => name.startsWith(`${outputBase}.`))292 .map((name) => join(tmpDir, name))293 .sort((a, b) => statSync(b).size - statSync(a).size)[0];294 if (!downloaded) throw new Error('yt-dlp proxy media fallback did not produce an output file');295 assertDownloadedFile(downloaded, 'yt-dlp proxy media fallback');296 return downloaded;297}298
299async function ytdlpWithProxyRetries(buildArgs, { freshProxyUrl, cookiesPath, label, attempts = 4 }) {300 let lastErr;301 for (let attempt = 1; attempt <= attempts; attempt++) {302 const proxyUrl = await freshProxyUrl();303 const args = buildArgs(proxyUrl);304 if (cookiesPath) args.push('--cookies', cookiesPath);305 try {306 return await withHeartbeat(307 () => ytdlp(args, { maxBuffer: 50 * 1024 * 1024, timeout: 600_000 }),308 attempt === 1 ? label : `${label} (attempt ${attempt}/${attempts})`,309 );310 } catch (err) {311 lastErr = err;312 if (attempt >= attempts || !isTransientProxyError(err)) throw err;313 console.log(` ${label} attempt ${attempt}/${attempts} failed (${err.message}); retrying with fresh proxy session...`);314 await sleep(1_500 * attempt);315 }316 }317 throw lastErr;318}319
320// ── Main Actor Logic ───────────────────────────────────────────────────────321
322await Actor.init();323
324Actor.on('aborting', async () => {325 await sleep(1000);326 await Actor.exit();327});328
329await ensureYtDlp();330
331const input = (await Actor.getInput()) || {};332const videoUrls = input.videoUrls || [];333const audioFormat = input.audioFormat || 'm4a';334const audioBitrate = input.audioBitrate || '192';335const embedMetadata = input.embedMetadata !== false;336const sleepMax = input.sleepBetweenUrls || 12;337const cookiesText = input.cookies || '';338const proxyInput = input.proxyConfiguration || {};339const useApifyProxy = proxyInput.useApifyProxy !== false;340const proxyCountry = proxyInput.apifyProxyCountry || 'US';341const allowProxyMediaDownload = input.allowProxyMediaDownload !== false;342const continueOnError = input.continueOnError === true;343
344if (!videoUrls.length) {345 console.log('No video URLs provided.');346 await Actor.exit();347 process.exit(0);348}349
350console.log(351 `Processing ${videoUrls.length} video(s), format=${audioFormat}, bitrate=${audioBitrate}k, embed=${embedMetadata}`,352);353
354// Parse cookies355let cookiesPath = null;356if (cookiesText) {357 cookiesPath = parseCookiesTxt(cookiesText);358 console.log('Cookies loaded from input');359}360
361const conversionFormats = ['mp3', 'm4a', 'flac', 'wav'];362const kvStoreId = process.env.APIFY_DEFAULT_KEY_VALUE_STORE_ID;363const kvBaseUrl = kvStoreId ? `https://api.apify.com/v2/key-value-stores/${kvStoreId}/records` : null;364
365let failedCount = 0;366let downloadedCount = 0;367
368for (let i = 0; i < videoUrls.length; i++) {369 const url = videoUrls[i];370 console.log(`[${i + 1}/${videoUrls.length}] Processing: ${url}`);371
372 const tmpDir = mkdtempSync(join(tmpdir(), 'ytdlp-'));373
374 try {375 // ── Proxy setup ───────────────────────────────────────────376 let proxyUrl = null;377 let proxyTier = 'none';378 let proxyConfig = null;379 // YouTube blocks datacenter IPs for API calls, so go straight to residential380 if (useApifyProxy) {381 console.log(' Setting up residential proxy...');382 proxyConfig = await Actor.createProxyConfiguration({383 groups: ['RESIDENTIAL'],384 countryCode: proxyCountry,385 });386 if (proxyConfig) {387 proxyUrl = await proxyConfig.newUrl(`session_${randomBytes(4).toString('hex')}`);388 proxyTier = 'residential';389 }390 }391 const freshProxyUrl = async () => {392 if (!proxyConfig) return null;393 return proxyConfig.newUrl(`session_${randomBytes(4).toString('hex')}`);394 };395
396 // ── Download ──────────────────────────────────────────────397 // Strategy: use yt-dlp defaults first, then fall back to alternate398 // YouTube clients. Media downloads go through residential proxy for399 // reliability; direct CDN downloads are intentionally disabled.400
401 console.log(' Fetching video metadata via proxy...');402 let info = await extractInfoWithProxyRetries(403 url,404 { proxyUrl, cookiesPath },405 { freshProxyUrl, label: 'Fetching video metadata' },406 );407 if (!hasDirectAudioFormats(info)) {408 console.log(409 ' No audio-only formats from yt-dlp default clients; retrying with android_vr/mweb and fresh proxy session...',410 );411 try {412 proxyUrl = await freshProxyUrl();413 info = await extractInfoWithProxyRetries(414 url,415 { proxyUrl, cookiesPath, playerClients: 'android_vr,mweb', useExtractorArgs: true },416 { freshProxyUrl, label: 'Retrying video metadata with android_vr/mweb' },417 );418 } catch (retryErr) {419 console.log(` android_vr/mweb metadata retry failed (${retryErr.message})`);420 }421 }422 if (!hasDirectAudioFormats(info)) {423 console.log(' Still no audio-only formats; retrying with web_embedded/default and fresh proxy session...');424 try {425 proxyUrl = await freshProxyUrl();426 info = await extractInfoWithProxyRetries(427 url,428 { proxyUrl, cookiesPath, playerClients: 'web_embedded,default', useExtractorArgs: true },429 { freshProxyUrl, label: 'Retrying video metadata with web_embedded/default' },430 );431 } catch (retryErr) {432 console.log(` web_embedded/default metadata retry failed (${retryErr.message})`);433 }434 }435 if (!hasDirectAudioFormats(info)) {436 console.log(' Still no audio-only formats; retrying metadata with TV clients and fresh proxy session...');437 proxyUrl = await freshProxyUrl();438 info = await extractInfoWithProxyRetries(439 url,440 {441 proxyUrl,442 cookiesPath,443 playerClients: 'tv_simply,tv_downgraded,tv,tv_embedded',444 useExtractorArgs: true,445 },446 { freshProxyUrl, label: 'Retrying video metadata with TV clients' },447 );448 }449 const title = info.title || 'Unknown';450 const videoId = info.id || 'unknown';451 const duration = info.duration || 0;452 const channel = info.channel || info.uploader || '';453 let selectedFormat = null;454 let sourceExt = audioFormat === 'opus' ? 'webm' : audioFormat;455 let sourceCodec = 'unknown';456 let sourceBitrate = null;457 let needsConversion = false;458 let rawPath;459 let proxyMediaUsed = false;460
461 if (!allowProxyMediaDownload) {462 throw new Error('Media downloads now require proxy media download because direct CDN downloading is disabled. Set allowProxyMediaDownload=true or omit it.');463 }464
465 if (hasDirectAudioFormats(info)) {466 selectedFormat = selectAudioFormat(info, audioFormat);467 sourceExt = selectedFormat.ext || info.ext || 'm4a';468 sourceCodec = selectedFormat.acodec || 'unknown';469 sourceBitrate = selectedFormat.abr || selectedFormat.tbr || null;470 const requestedDirectFormat =471 audioFormat === 'best' ||472 (audioFormat === 'opus' && (sourceExt === 'webm' || sourceCodec.includes('opus'))) ||473 audioFormat === sourceExt;474 needsConversion = conversionFormats.includes(audioFormat) && !requestedDirectFormat;475
476 console.log(477 ` Selected audio-only format ${selectedFormat.format_id || 'unknown'} (${sourceExt}, ${sourceCodec}, ${sourceBitrate || '?'} kbps)`,478 );479
480 rawPath = join(tmpDir, `${safeFilename(title)}.raw.${sourceExt}`);481 console.log(' Downloading selected audio format with yt-dlp via residential proxy...');482 proxyMediaUsed = true;483 await ytdlpWithProxyRetries(484 (mediaProxyUrl) => {485 const args = [486 url,487 '--no-playlist',488 '--quiet',489 '--no-warnings',490 '--format',491 selectedFormat.format_id || 'bestaudio/best',492 '--user-agent',493 randomUserAgent(),494 '--js-runtimes',495 'node',496 '--force-ipv4',497 '--socket-timeout',498 '30',499 '--retries',500 '2',501 '--fragment-retries',502 '2',503 '--force-overwrites',504 '--no-part',505 '--output',506 rawPath,507 ];508 if (mediaProxyUrl) args.push('--proxy', mediaProxyUrl);509 return args;510 },511 {512 freshProxyUrl,513 cookiesPath,514 label: 'Downloading selected format with yt-dlp via proxy',515 },516 );517 console.log(` Downloaded ${formatBytes(assertDownloadedFile(rawPath, 'Proxy media download'))}`);518 } else {519 console.log(' No direct audio-only formats found; using yt-dlp audio extraction via residential proxy...');520 proxyMediaUsed = true;521 const outputBase = `proxy-audio-${randomBytes(4).toString('hex')}`;522 const outputTemplate = join(tmpDir, `${outputBase}.%(ext)s`);523 await ytdlpWithProxyRetries(524 (mediaProxyUrl) => {525 const args = [526 url,527 '--no-playlist',528 '--quiet',529 '--no-warnings',530 '--format',531 'bestaudio/best',532 '--extract-audio',533 '--audio-format',534 ytdlpAudioFormat(audioFormat),535 '--audio-quality',536 `${audioBitrate}K`,537 '--user-agent',538 randomUserAgent(),539 '--js-runtimes',540 'node',541 '--force-ipv4',542 '--socket-timeout',543 '30',544 '--retries',545 '2',546 '--fragment-retries',547 '2',548 '--force-overwrites',549 '--no-part',550 '--output',551 outputTemplate,552 ];553 if (mediaProxyUrl) args.push('--proxy', mediaProxyUrl);554 return args;555 },556 {557 freshProxyUrl,558 cookiesPath,559 label: 'Downloading with yt-dlp audio extraction via proxy',560 },561 );562 rawPath = readdirSync(tmpDir)563 .filter((name) => name.startsWith(`${outputBase}.`))564 .map((name) => join(tmpDir, name))565 .sort((a, b) => statSync(b).size - statSync(a).size)[0];566 if (!rawPath) throw new Error('yt-dlp audio extraction did not produce an output file');567 sourceExt = extname(rawPath).replace(/^\./, '') || sourceExt;568 sourceCodec = 'unknown';569 sourceBitrate = null;570 needsConversion = false;571 console.log(` Downloaded ${formatBytes(assertDownloadedFile(rawPath, 'Proxy media download'))}`);572 }573 assertDownloadedFile(rawPath, 'Audio download');574
575 // Determine final audio path. Avoid conversion whenever selected source already matches requested output.576 let audioPath;577 let wasConverted = false;578 if (needsConversion) {579 audioPath = join(tmpDir, `${safeFilename(title)}.${audioFormat}`);580 console.log(` Converting to ${audioFormat} with ffmpeg...`);581 execSync(`ffmpeg -y -i "${rawPath}" -vn ${ffmpegAudioArgs(audioFormat, audioBitrate)} "${audioPath}"`, {582 stdio: ['ignore', 'pipe', 'pipe'],583 timeout: 300_000,584 });585 wasConverted = true;586 console.log(` Converted: ${formatBytes(statSync(audioPath).size)}`);587 } else {588 audioPath = join(tmpDir, `${safeFilename(title)}.${audioFormat === 'opus' ? 'webm' : sourceExt}`);589 execSync(`mv "${rawPath}" "${audioPath}"`);590 }591
592 if (embedMetadata && audioFormat !== 'wav') {593 console.log(' Embedding metadata...');594 try {595 const safeTitle = (info.title || '').replace(/"/g, '\\"');596 const safeArtist = (channel || '').replace(/"/g, '\\"');597 const tmpAudio = `${audioPath}.tmp.${extname(audioPath).replace(/^\./, '')}`;598 execSync(599 `ffmpeg -y -i "${audioPath}" -c copy ` +600 `-metadata title="${safeTitle}" ` +601 `-metadata artist="${safeArtist}" ` +602 `-id3v2_version 3 "${tmpAudio}" && mv "${tmpAudio}" "${audioPath}"`,603 { stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 },604 );605 } catch (metaErr) {606 console.log(` Metadata embedding skipped (${metaErr.message})`);607 }608 }609
610 // ── Store results ─────────────────────────────────────────611 const audioFile = readFileSync(audioPath);612 const fileExt = extname(audioPath).replace(/^\./, '');613 const kvKey = `audio-${videoId}`;614 const contentType = mimeType(fileExt);615
616 console.log(` Uploading ${formatBytes(audioFile.length)} to key-value store...`);617 await Actor.setValue(kvKey, audioFile, { contentType });618 console.log(` ✓ Done: "${title}" (${videoId}), ${formatDuration(duration)}, ${formatBytes(audioFile.length)}`);619
620 const item = {621 video_id: videoId,622 video_url: url,623 video_title: title,624 channel,625 duration,626 audio_format: fileExt,627 file_size_bytes: audioFile.length,628 source_format_id: selectedFormat.format_id || null,629 source_ext: sourceExt,630 source_codec: sourceCodec,631 source_bitrate: sourceBitrate,632 was_converted: wasConverted,633 proxy_media_used: proxyMediaUsed,634 kv_store_key: kvKey,635 proxy_tier_used: proxyTier,636 status: 'downloaded',637 };638 if (kvBaseUrl) item.audio_url = `${kvBaseUrl}/${kvKey}`;639 await Actor.pushData(item);640 downloadedCount++;641 } catch (err) {642 failedCount++;643 console.error(` ✗ Failed: ${url} — ${err.message}`);644 await Actor.pushData({645 video_url: url,646 status: 'error',647 error: err.message.slice(0, 500),648 });649 } finally {650 try {651 rmSync(tmpDir, { recursive: true, force: true });652 } catch {}653 }654
655 // Random delay between URLs656 if (i < videoUrls.length - 1) {657 const delaySec = 5 + Math.random() * (sleepMax - 5);658 console.log(` Sleeping ${delaySec.toFixed(1)}s before next URL...`);659 await sleep(Math.round(delaySec * 1000));660 }661}662
663console.log(`Finished processing all URLs: ${downloadedCount} downloaded, ${failedCount} failed`);664if (failedCount > 0 && !continueOnError) {665 throw new Error(`${failedCount} of ${videoUrls.length} video(s) failed. Set continueOnError=true to keep the Actor run successful despite per-video errors.`);666}667await 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}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>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?)