@omnizap-system/omnizap 2.6.0 → 2.6.2

package/app/modules/playModule/playCommandMediaClient.js

@@ -0,0 +1,1872 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import logger from '#logger';
+import { getPlayExecutionOptions, getPlayOperationalLimits, getPlayReadyTitle, getPlayText } from './playConfigRuntime.js';
+import { DEFAULT_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS, MEDIA_INFO_TIMEOUT_MS, PLAY_YTMP3_ENABLED, PLAY_YTMP3_API_BASE_URL, PLAY_YTMP3_API_DOWNLOAD_PATH, PLAY_YTMP3_POLL_INTERVAL_MS, PLAY_YTMP3_SEARCH_BASE_URL, PLAY_YTMP3_SEARCH_PATH, PLAY_YTMP3_VIDEO_DEFAULT_QUALITY, MAX_SEARCH_RESULTS, MAX_MEDIA_BYTES, MAX_MEDIA_MB_LABEL, THUMBNAIL_TIMEOUT_MS, MAX_THUMB_BYTES, VIDEO_PROCESS_TIMEOUT_MS, VIDEO_FORCE_TRANSCODE, FFMPEG_BIN, FFPROBE_BIN, SEARCH_CACHE_TTL_MS, MAX_SEARCH_CACHE_ENTRIES, MAX_REDIRECTS, MAX_ERROR_BODY_BYTES, MAX_META_BODY_CHARS, TRANSIENT_HTTP_STATUSES, TRANSIENT_NETWORK_CODES, YTDLS_ENDPOINTS, ERROR_CODES, KNOWN_ERROR_CODES, TYPE_CONFIG, PLAY_DOWNLOADS_DIR } from './playCommandConstants.js';
+
+const createError = (code, message, meta) => {
+  const error = new Error(message);
+  error.code = code;
+  if (meta) error.meta = meta;
+  return error;
+};
+
+const withErrorMeta = (error, meta) => {
+  if (!error || typeof error !== 'object') return error;
+  error.meta = {
+    ...(error.meta || {}),
+    ...(meta || {}),
+  };
+  return error;
+};
+
+const isAbortError = (error) => error?.name === 'AbortError' || error?.code === 'ABORT_ERR' || error?.code === 'ECONNABORTED';
+
+const normalizeRequestError = (error, { timeoutMessage, fallbackMessage, fallbackCode }) => {
+  if (KNOWN_ERROR_CODES.has(error?.code) && error?.message) return error;
+  if (isAbortError(error)) {
+    return createError(ERROR_CODES.TIMEOUT, timeoutMessage, {
+      rawCode: error?.code || error?.name || null,
+      technical: true,
+    });
+  }
+  return createError(fallbackCode || ERROR_CODES.API, fallbackMessage, {
+    cause: error?.message || 'unknown',
+    rawCode: error?.code || error?.name || null,
+    technical: true,
+  });
+};
+
+const normalizePlayError = (error) => {
+  if (KNOWN_ERROR_CODES.has(error?.code) && error?.message) return error;
+  if (isAbortError(error)) {
+    return createError(ERROR_CODES.TIMEOUT, getPlayText('user_error_timeout', 'A operação demorou mais que o esperado. Tente novamente.'), {
+      rawCode: error?.code || error?.name || null,
+      technical: true,
+    });
+  }
+  return createError(ERROR_CODES.API, getPlayText('user_error_technical_generic', 'Não foi possível processar sua solicitação agora. Tente novamente em instantes.'), {
+    cause: error?.message || 'unknown',
+    rawCode: error?.code || error?.name || null,
+    technical: true,
+  });
+};
+
+const delay = (ms) => new Promise((resolve) => setTimeout(() => resolve(null), ms));
+
+const renderTemplate = (value, variables = {}) => {
+  let text = String(value || '');
+  for (const [key, variableValue] of Object.entries(variables || {})) {
+    text = text.replaceAll(`<${key}>`, String(variableValue ?? ''));
+  }
+  return text;
+};
+
+const playText = (key, fallback, variables) => renderTemplate(getPlayText(key, fallback), variables);
+
+const getLimits = () => getPlayOperationalLimits();
+
+const getExecutionOptions = () => getPlayExecutionOptions();
+
+const createPlayProcessLimiter = () => {
+  let active = 0;
+  const queue = [];
+
+  const resolveLimit = () => Math.max(1, Number(getLimits().max_concurrent_jobs ?? 2));
+
+  const pump = () => {
+    const limit = resolveLimit();
+    while (active < limit && queue.length) {
+      const next = queue.shift();
+      if (!next) continue;
+      active += 1;
+      Promise.resolve()
+        .then(next.task)
+        .then(next.resolve, next.reject)
+        .finally(() => {
+          active = Math.max(0, active - 1);
+          pump();
+        });
+    }
+  };
+
+  const run = (task) =>
+    new Promise((resolve, reject) => {
+      queue.push({ task, resolve, reject });
+      pump();
+    });
+
+  const stats = () => ({ active, queued: queue.length, limit: resolveLimit() });
+
+  return { run, stats };
+};
+
+const playProcessLimiter = createPlayProcessLimiter();
+
+const runWithPlayProcessSlot = async (task, meta = {}) => {
+  const before = playProcessLimiter.stats();
+  if (before.active >= before.limit) {
+    logger.warn('Play process: aguardando slot de execução.', {
+      endpoint: meta?.endpoint || YTDLS_ENDPOINTS.download,
+      command: meta?.command || null,
+      activeJobs: before.active,
+      queuedJobs: before.queued,
+      maxConcurrentJobs: before.limit,
+    });
+  }
+
+  return playProcessLimiter.run(task);
+};
+
+const truncateText = (value, maxChars = getLimits().max_meta_body_chars || MAX_META_BODY_CHARS) => {
+  if (typeof value !== 'string') return '';
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, maxChars)}...[truncated]`;
+};
+
+const toNumberOrNull = (value) => {
+  if (value === null || value === undefined || value === '') return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+};
+
+const pickFirstString = (source, keys) => {
+  if (!source || typeof source !== 'object') return null;
+  for (const key of keys) {
+    const raw = source[key];
+    if (typeof raw === 'string' && raw.trim()) return raw.trim();
+  }
+  return null;
+};
+
+const ensureHttpUrl = (value) => {
+  if (!value || typeof value !== 'string') return null;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol === 'http:' || url.protocol === 'https:') return url.toString();
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+const resolveHttpUrl = (value, baseUrl = null) => {
+  if (!value || typeof value !== 'string') return null;
+  try {
+    const resolved = baseUrl ? new URL(value.trim(), baseUrl) : new URL(value.trim());
+    if (resolved.protocol === 'http:' || resolved.protocol === 'https:') {
+      return resolved.toString();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+const isYouTubeUrl = (value) => {
+  const normalized = ensureHttpUrl(value);
+  if (!normalized) return false;
+  try {
+    const hostname = new URL(normalized).hostname.toLowerCase();
+    return hostname === 'youtube.com' || hostname.endsWith('.youtube.com') || hostname === 'youtu.be' || hostname.endsWith('.youtu.be') || hostname === 'youtubekids.com' || hostname.endsWith('.youtubekids.com');
+  } catch {
+    return false;
+  }
+};
+
+const formatNumber = (value) => {
+  const number = toNumberOrNull(value);
+  if (number === null) return null;
+  return number.toLocaleString('pt-BR');
+};
+
+const formatDuration = (value) => {
+  if (value === null || value === undefined) return null;
+  const number = toNumberOrNull(value);
+  if (number !== null) {
+    const totalSeconds = Math.max(0, Math.floor(number));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+      return `${hours}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+    }
+    return `${minutes}:${String(seconds).padStart(2, '0')}`;
+  }
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  return null;
+};
+
+const formatVideoInfo = (videoInfo) => {
+  if (!videoInfo || typeof videoInfo !== 'object') return null;
+  const lines = [];
+  const title = pickFirstString(videoInfo, ['title', 'titulo', 'name']);
+  if (title) lines.push(`🎧 ${title}`);
+  const channel = pickFirstString(videoInfo, ['channel', 'uploader', 'uploader_name', 'author']);
+  if (channel) lines.push(`📺 ${channel}`);
+  const duration = formatDuration(videoInfo.duration);
+  if (duration) lines.push(`⏱ ${duration}`);
+  const id = pickFirstString(videoInfo, ['id', 'videoId', 'video_id']);
+  if (id) lines.push(`🆔 ${id}`);
+  return lines.length ? lines.join('\n') : null;
+};
+
+const getThumbnailUrl = (videoInfo) => {
+  if (!videoInfo || typeof videoInfo !== 'object') return null;
+
+  const direct = pickFirstString(videoInfo, ['thumbnail', 'thumb', 'thumbnail_url', 'thumbnailUrl', 'thumb_url', 'image', 'cover', 'artwork']);
+  const directUrl = ensureHttpUrl(direct);
+  if (directUrl) return directUrl;
+
+  const objectThumb = videoInfo.thumbnail;
+  if (objectThumb && typeof objectThumb === 'object') {
+    const objectUrl = ensureHttpUrl(objectThumb.url || objectThumb.src);
+    if (objectUrl) return objectUrl;
+  }
+
+  if (Array.isArray(videoInfo.thumbnails)) {
+    for (const thumb of videoInfo.thumbnails) {
+      const thumbUrl = ensureHttpUrl(thumb?.url || thumb?.src);
+      if (thumbUrl) return thumbUrl;
+    }
+  }
+
+  return null;
+};
+
+const buildQueueStatusText = (status) => {
+  if (!status?.fila) return null;
+
+  const fila = status.fila;
+  const downloadsAhead = toNumberOrNull(fila.downloads_a_frente);
+  const position = toNumberOrNull(fila.posicao_na_fila);
+  const totalQueued = toNumberOrNull(fila.enfileirados);
+
+  if (downloadsAhead === null && position === null && totalQueued === null) {
+    return null;
+  }
+
+  const lines = [];
+  if (position !== null) lines.push(`📍 Posição na fila: ${position}`);
+  if (downloadsAhead !== null) lines.push(`🚀 Downloads à frente: ${downloadsAhead}`);
+  if (!lines.length && totalQueued !== null) lines.push(`📦 Itens na fila: ${totalQueued}`);
+
+  return lines.join('\n');
+};
+
+const buildReadyCaption = (type, infoText) => {
+  const config = TYPE_CONFIG[type];
+  if (!config) return infoText || '';
+  const readyTitle = getPlayReadyTitle(type) || config.readyTitle;
+  if (!infoText) return readyTitle;
+  return `${readyTitle}\n──────────────\n${infoText}`;
+};
+
+const buildTempFilePath = (requestId, type) => {
+  const safeId = String(requestId || 'req')
+    .replace(/[^a-z0-9-_]+/gi, '')
+    .slice(0, 48);
+  const ext = type === 'audio' ? 'mp3' : 'mp4';
+  return path.join(PLAY_DOWNLOADS_DIR, `play-${safeId}-${__timeNowMs()}.${ext}`);
+};
+
+const safeUnlink = async (filePath) => {
+  if (!filePath) return;
+  try {
+    await fs.promises.unlink(filePath);
+  } catch {
+    return;
+  }
+};
+
+const createAbortSignal = (timeoutMs) => {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return { signal: undefined, cleanup: () => {} };
+  }
+  const controller = new globalThis.AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  return {
+    signal: controller.signal,
+    cleanup: () => clearTimeout(timeoutId),
+  };
+};
+
+const normalizeHeaderValue = (value) => {
+  if (Array.isArray(value)) return value[0];
+  return value;
+};
+
+const getHeaderValue = (headers, key) => {
+  if (!headers || typeof headers !== 'object') return undefined;
+  const lowerKey = key.toLowerCase();
+  const raw = headers[lowerKey] ?? headers[key] ?? headers[key.toUpperCase()];
+  return normalizeHeaderValue(raw);
+};
+
+const normalizeMimeType = (value) => {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const mime = value.split(';', 1)[0]?.trim().toLowerCase();
+  return mime || null;
+};
+
+const resolveMediaMimeType = (type, contentType) => {
+  const normalized = normalizeMimeType(contentType);
+
+  if (type === 'audio') {
+    return normalized && normalized.startsWith('audio/') ? normalized : TYPE_CONFIG.audio.mimeFallback;
+  }
+
+  if (type === 'video') {
+    return normalized && normalized.startsWith('video/') ? normalized : TYPE_CONFIG.video.mimeFallback;
+  }
+
+  return normalized || 'application/octet-stream';
+};
+
+const runBinaryCommand = (command, args, { timeoutMs = VIDEO_PROCESS_TIMEOUT_MS } = {}) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let timedOut = false;
+    const maxCapturedBytes = (getLimits().max_error_body_bytes || MAX_ERROR_BODY_BYTES) * 4;
+
+    const appendChunk = (chunks, chunk, bytes) => {
+      if (!chunk || bytes >= maxCapturedBytes) return bytes;
+      const current = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, maxCapturedBytes - bytes);
+      if (remaining <= 0) return bytes;
+      const accepted = current.length <= remaining ? current : current.subarray(0, remaining);
+      chunks.push(accepted);
+      return bytes + accepted.length;
+    };
+
+    child.stdout.on('data', (chunk) => {
+      stdoutBytes = appendChunk(stdoutChunks, chunk, stdoutBytes);
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderrBytes = appendChunk(stderrChunks, chunk, stderrBytes);
+    });
+
+    const timeoutId =
+      Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+          }, timeoutMs)
+        : null;
+    let settled = false;
+
+    const finalize = (handler) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      handler();
+    };
+
+    child.on('error', (error) => {
+      finalize(() => reject(error));
+    });
+
+    child.on('close', (code, signal) => {
+      finalize(() => {
+        const stdout = Buffer.concat(stdoutChunks, stdoutBytes).toString('utf-8').trim();
+        const stderr = Buffer.concat(stderrChunks, stderrBytes).toString('utf-8').trim();
+
+        if (!timedOut && code === 0) {
+          resolve({ stdout, stderr });
+          return;
+        }
+
+        const error = new Error(stderr || playText('binary_exec_failed', `Falha ao executar ${path.basename(command)}.`, { command: path.basename(command) }));
+        error.code = timedOut ? 'ETIMEDOUT' : 'EPROCESS';
+        error.exitCode = code;
+        error.signal = signal || null;
+        error.stderr = stderr;
+        error.stdout = stdout;
+        reject(error);
+      });
+    });
+  });
+
+const normalizeBinaryError = (error, { timeoutMessage, fallbackMessage, endpoint, requestId, command, outputPath }) => {
+  if (KNOWN_ERROR_CODES.has(error?.code) && error?.message) return error;
+  if (error?.code === 'ETIMEDOUT') {
+    return createError(ERROR_CODES.TIMEOUT, timeoutMessage, {
+      endpoint,
+      requestId,
+      command,
+      rawCode: error?.code || null,
+      technical: true,
+    });
+  }
+  return createError(ERROR_CODES.API, fallbackMessage, {
+    endpoint,
+    requestId,
+    command,
+    outputPath: outputPath || null,
+    rawCode: error?.code || null,
+    exitCode: error?.exitCode ?? null,
+    signal: error?.signal || null,
+    cause: truncateText(error?.stderr || error?.message || 'unknown'),
+    technical: true,
+  });
+};
+
+const probeVideoStreams = async (filePath, requestId, endpoint) => {
+  try {
+    const result = await runWithPlayProcessSlot(() => runBinaryCommand(FFPROBE_BIN, ['-v', 'error', '-print_format', 'json', '-show_streams', filePath]), { endpoint, command: FFPROBE_BIN });
+    const parsed = JSON.parse(result.stdout || '{}');
+    const streams = Array.isArray(parsed?.streams) ? parsed.streams : [];
+    const videoStream = streams.find((stream) => stream?.codec_type === 'video') || null;
+    const audioStream = streams.find((stream) => stream?.codec_type === 'audio') || null;
+
+    return {
+      hasVideo: Boolean(videoStream),
+      hasAudio: Boolean(audioStream),
+      videoCodec: videoStream?.codec_name || null,
+      audioCodec: audioStream?.codec_name || null,
+    };
+  } catch (error) {
+    const normalized = normalizeBinaryError(error, {
+      timeoutMessage: playText('probe_timeout', 'Timeout ao analisar o vídeo recebido.'),
+      fallbackMessage: playText('probe_failed', 'Falha ao validar o vídeo recebido.'),
+      endpoint,
+      requestId,
+      command: FFPROBE_BIN,
+    });
+    throw normalized;
+  }
+};
+
+const transcodeVideoForWhatsapp = async (filePath, requestId, endpoint) => {
+  const outputPath = `${filePath}.wa.mp4`;
+
+  try {
+    await safeUnlink(outputPath);
+
+    await runWithPlayProcessSlot(
+      () =>
+        runBinaryCommand(FFMPEG_BIN, ['-y', '-i', filePath, '-map', '0:v:0', '-map', '0:a:0?', '-c:v', 'libx264', '-preset', 'veryfast', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-c:a', 'aac', '-b:a', '128k', '-ar', '44100', '-ac', '2', outputPath], {
+          timeoutMs: VIDEO_PROCESS_TIMEOUT_MS,
+        }),
+      { endpoint, command: FFMPEG_BIN },
+    );
+
+    const stats = await fs.promises.stat(outputPath);
+    const transcodedBytes = Number(stats?.size || 0);
+
+    if (transcodedBytes <= 0) {
+      throw createError(ERROR_CODES.API, playText('transcode_output_invalid', 'Falha ao gerar vídeo compatível para envio.'), {
+        endpoint,
+        requestId,
+        outputPath,
+        technical: true,
+      });
+    }
+
+    if (transcodedBytes > MAX_MEDIA_BYTES) {
+      throw createError(ERROR_CODES.TOO_BIG, playText('media_too_big', `O arquivo excede o limite permitido de ${MAX_MEDIA_MB_LABEL} MB.`, { max_mb: MAX_MEDIA_MB_LABEL }), {
+        endpoint,
+        requestId,
+        bytes: transcodedBytes,
+        technical: false,
+      });
+    }
+
+    await fs.promises.rename(outputPath, filePath);
+    return transcodedBytes;
+  } catch (error) {
+    await safeUnlink(outputPath);
+    const normalized = normalizeBinaryError(error, {
+      timeoutMessage: playText('transcode_timeout', 'Timeout ao normalizar o vídeo para envio.'),
+      fallbackMessage: playText('transcode_failed', 'Falha ao converter o vídeo para um formato compatível.'),
+      endpoint,
+      requestId,
+      command: FFMPEG_BIN,
+      outputPath,
+    });
+    throw normalized;
+  }
+};
+
+const resolveHttpModule = (urlObj) => (urlObj.protocol === 'https:' ? https : http);
+
+const shouldFollowRedirect = (status, location, redirectCount, maxRedirects) => status >= 300 && status < 400 && Boolean(location) && redirectCount < maxRedirects;
+
+const readResponseBuffer = async (stream, { maxBytes = Infinity, tooBigMessage } = {}) => {
+  const chunks = [];
+  let total = 0;
+
+  for await (const chunk of stream) {
+    const current = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += current.length;
+
+    if (Number.isFinite(maxBytes) && total > maxBytes) {
+      stream.destroy();
+      throw createError(ERROR_CODES.TOO_BIG, tooBigMessage || playText('content_too_big', 'Conteúdo excede o limite permitido.'), { bytes: total, technical: false });
+    }
+
+    chunks.push(current);
+  }
+
+  return Buffer.concat(chunks, total);
+};
+
+const httpRequest = ({ url, method = 'GET', headers = {}, body = null, timeoutMs = DEFAULT_TIMEOUT_MS, maxRedirects = 0, redirectCount = 0, endpoint = 'unknown', timeoutMessage = playText('http_timeout', 'Timeout na requisição HTTP.'), fallbackMessage = playText('http_failed', 'Falha na requisição HTTP.'), onResponse }) =>
+  new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const httpModule = resolveHttpModule(urlObj);
+    const { signal, cleanup } = createAbortSignal(timeoutMs);
+    const normalizedMethod = String(method || 'GET').toUpperCase();
+
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      fn();
+    };
+
+    const settleResolve = (value) => settle(() => resolve(value));
+    const settleReject = (error) => settle(() => reject(error));
+
+    const req = httpModule.request(
+      urlObj,
+      {
+        method: normalizedMethod,
+        headers: {
+          Accept: '*/*',
+          ...(headers && typeof headers === 'object' ? headers : {}),
+        },
+        signal,
+      },
+      (res) => {
+        const status = res.statusCode || 0;
+        const location = getHeaderValue(res.headers, 'location');
+        res.on('error', (error) => {
+          const normalized = normalizeRequestError(error, {
+            timeoutMessage,
+            fallbackMessage,
+          });
+          settleReject(withErrorMeta(normalized, { endpoint, status }));
+        });
+
+        if (shouldFollowRedirect(status, location, redirectCount, maxRedirects)) {
+          logger.debug('HTTP redirect.', {
+            endpoint,
+            status,
+            location: String(location),
+            redirectCount: redirectCount + 1,
+          });
+          const nextUrl = new URL(String(location), urlObj).toString();
+          res.resume();
+          settleResolve(
+            httpRequest({
+              url: nextUrl,
+              method: normalizedMethod,
+              headers,
+              body,
+              timeoutMs,
+              maxRedirects,
+              redirectCount: redirectCount + 1,
+              endpoint,
+              timeoutMessage,
+              fallbackMessage,
+              onResponse,
+            }),
+          );
+          return;
+        }
+
+        Promise.resolve(
+          onResponse({
+            res,
+            status,
+            headers: res.headers,
+            endpoint,
+            finalUrl: urlObj.toString(),
+          }),
+        )
+          .then(settleResolve)
+          .catch((error) => {
+            const normalized = normalizeRequestError(error, {
+              timeoutMessage,
+              fallbackMessage,
+            });
+            settleReject(withErrorMeta(normalized, { endpoint, status }));
+          });
+      },
+    );
+
+    req.on('error', (error) => {
+      const normalized = normalizeRequestError(error, {
+        timeoutMessage,
+        fallbackMessage,
+      });
+      settleReject(withErrorMeta(normalized, { endpoint }));
+    });
+
+    if (body !== null && body !== undefined) {
+      req.write(body);
+    }
+
+    req.end();
+  });
+
+const requestJson = async ({ url, method = 'GET', data = null, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS, maxRedirects = getLimits().max_redirects ?? MAX_REDIRECTS, endpoint = 'unknown', timeoutMessage = playText('http_timeout', 'Timeout na requisição HTTP.'), fallbackMessage = playText('http_failed', 'Falha na requisição HTTP.') }) => {
+  const normalizedMethod = String(method || 'GET').toUpperCase();
+  let finalUrl = url;
+  let body = null;
+
+  const isGetLike = normalizedMethod === 'GET' || normalizedMethod === 'HEAD';
+  if (isGetLike && data && typeof data === 'object') {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(data)) {
+      if (value === null || value === undefined || value === '') continue;
+      searchParams.append(key, String(value));
+    }
+
+    const query = searchParams.toString();
+    if (query) {
+      const delimiter = finalUrl.includes('?') ? '&' : '?';
+      finalUrl = `${finalUrl}${delimiter}${query}`;
+    }
+  } else if (data !== null && data !== undefined) {
+    body = JSON.stringify(data);
+  }
+
+  const requestHeaders = {
+    Accept: 'application/json',
+    ...(headers && typeof headers === 'object' ? headers : {}),
+  };
+  if (body !== null && body !== undefined) {
+    requestHeaders['Content-Type'] = requestHeaders['Content-Type'] || 'application/json';
+  }
+
+  return httpRequest({
+    url: finalUrl,
+    method: normalizedMethod,
+    headers: requestHeaders,
+    body,
+    timeoutMs,
+    endpoint,
+    maxRedirects,
+    timeoutMessage,
+    fallbackMessage,
+    onResponse: async ({ res, status, endpoint: currentEndpoint }) => {
+      const bodyBuffer = await readResponseBuffer(res, {
+        maxBytes: (getLimits().max_error_body_bytes ?? MAX_ERROR_BODY_BYTES) * 4,
+      });
+      const rawText = bodyBuffer.toString('utf-8').trim();
+
+      if (status < 200 || status >= 300) {
+        throw createError(ERROR_CODES.API, fallbackMessage, {
+          endpoint: currentEndpoint,
+          status,
+          cause: truncateText(rawText || 'http_non_success'),
+          technical: true,
+        });
+      }
+
+      if (!rawText) return {};
+
+      try {
+        return JSON.parse(rawText);
+      } catch {
+        throw createError(ERROR_CODES.API, fallbackMessage, {
+          endpoint: currentEndpoint,
+          status,
+          cause: truncateText(rawText || 'invalid_json'),
+          technical: true,
+        });
+      }
+    },
+  });
+};
+
+const requestFile = async ({ url, filePath, timeoutMs = DOWNLOAD_TIMEOUT_MS, maxBytes = MAX_MEDIA_BYTES, endpoint = YTDLS_ENDPOINTS.download, timeoutMessage = playText('download_timeout', 'Timeout ao baixar o arquivo.'), fallbackMessage = playText('download_failed', 'Falha ao baixar o arquivo localmente.') }) => {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+
+  try {
+    return await httpRequest({
+      url,
+      timeoutMs,
+      endpoint,
+      maxRedirects: getLimits().max_redirects ?? MAX_REDIRECTS,
+      timeoutMessage,
+      fallbackMessage,
+      onResponse: async ({ res, status, headers, endpoint: currentEndpoint }) => {
+        if (status < 200 || status >= 300) {
+          const responseBody = await readResponseBuffer(res, {
+            maxBytes: getLimits().max_error_body_bytes ?? MAX_ERROR_BODY_BYTES,
+          });
+          throw createError(ERROR_CODES.API, fallbackMessage, {
+            endpoint: currentEndpoint,
+            status,
+            cause: truncateText(responseBody.toString('utf-8')),
+            technical: true,
+          });
+        }
+
+        const contentLength = toNumberOrNull(getHeaderValue(headers, 'content-length'));
+        if (contentLength !== null && contentLength > maxBytes) {
+          res.resume();
+          throw createError(ERROR_CODES.TOO_BIG, playText('media_too_big', `O arquivo excede o limite permitido de ${MAX_MEDIA_MB_LABEL} MB.`, { max_mb: MAX_MEDIA_MB_LABEL }), {
+            endpoint: currentEndpoint,
+            status,
+            bytes: contentLength,
+            technical: false,
+          });
+        }
+
+        const writeStream = fs.createWriteStream(filePath, { flags: 'w' });
+        let bytes = 0;
+
+        await new Promise((resolve, reject) => {
+          let settled = false;
+
+          const settleReject = (error) => {
+            if (settled) return;
+            settled = true;
+            writeStream.destroy();
+            res.destroy();
+            reject(error);
+          };
+
+          const settleResolve = () => {
+            if (settled) return;
+            settled = true;
+            resolve(null);
+          };
+
+          res.on('data', (chunk) => {
+            bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk || ''));
+            if (bytes > maxBytes) {
+              settleReject(
+                createError(ERROR_CODES.TOO_BIG, playText('media_too_big', `O arquivo excede o limite permitido de ${MAX_MEDIA_MB_LABEL} MB.`, { max_mb: MAX_MEDIA_MB_LABEL }), {
+                  endpoint: currentEndpoint,
+                  status,
+                  bytes,
+                  technical: false,
+                }),
+              );
+            }
+          });
+
+          res.on('error', settleReject);
+          writeStream.on('error', settleReject);
+          writeStream.on('finish', settleResolve);
+          res.pipe(writeStream);
+        });
+
+        if (bytes <= 0) {
+          throw createError(ERROR_CODES.API, playText('download_invalid_media', 'Falha ao baixar mídia válida.'), {
+            endpoint: currentEndpoint,
+            status,
+            bytes,
+            filePath,
+            technical: true,
+          });
+        }
+
+        return {
+          bytes,
+          contentType: normalizeMimeType(getHeaderValue(headers, 'content-type')),
+        };
+      },
+    });
+  } catch (error) {
+    await safeUnlink(filePath);
+    throw error;
+  }
+};
+
+const requestBuffer = async ({ url, timeoutMs = getLimits().thumbnail_timeout_ms ?? THUMBNAIL_TIMEOUT_MS, maxBytes = getLimits().max_thumb_bytes ?? MAX_THUMB_BYTES, endpoint = YTDLS_ENDPOINTS.thumbnail }) =>
+  httpRequest({
+    url,
+    method: 'GET',
+    timeoutMs,
+    endpoint,
+    maxRedirects: getLimits().max_redirects ?? MAX_REDIRECTS,
+    timeoutMessage: playText('thumbnail_timeout', 'Timeout ao baixar a thumbnail.'),
+    fallbackMessage: playText('thumbnail_failed', 'Falha ao baixar a thumbnail.'),
+    onResponse: async ({ res, status, headers, endpoint: currentEndpoint }) => {
+      if (status < 200 || status >= 300) {
+        res.resume();
+        throw createError(ERROR_CODES.API, playText('thumbnail_failed', 'Falha ao baixar a thumbnail.'), {
+          endpoint: currentEndpoint,
+          status,
+          technical: true,
+        });
+      }
+
+      const contentLength = toNumberOrNull(getHeaderValue(headers, 'content-length'));
+      if (contentLength !== null && contentLength > maxBytes) {
+        res.resume();
+        throw createError(ERROR_CODES.TOO_BIG, playText('thumbnail_too_big', 'Thumbnail excede o limite permitido.'), {
+          endpoint: currentEndpoint,
+          status,
+          bytes: contentLength,
+          technical: false,
+        });
+      }
+
+      return readResponseBuffer(res, {
+        maxBytes,
+        tooBigMessage: playText('thumbnail_too_big', 'Thumbnail excede o limite permitido.'),
+      });
+    },
+  });
+
+const httpClient = {
+  requestBuffer,
+  requestJson,
+  requestFile,
+};
+
+const isTransientError = (error) => {
+  if (!error) return false;
+  if (error.code === ERROR_CODES.TIMEOUT) return true;
+
+  const status = toNumberOrNull(error?.meta?.status);
+  if (status !== null && TRANSIENT_HTTP_STATUSES.has(status)) return true;
+
+  const rawCode = String(error?.meta?.rawCode || error?.code || '').toUpperCase();
+  return TRANSIENT_NETWORK_CODES.has(rawCode);
+};
+
+const retryAsync = async (operation, { retries = 0, shouldRetry = () => false, onRetry } = {}) => {
+  let attempt = 0;
+
+  while (true) {
+    try {
+      return await operation(attempt);
+    } catch (error) {
+      if (attempt >= retries || !shouldRetry(error)) {
+        throw error;
+      }
+
+      attempt += 1;
+      if (typeof onRetry === 'function') {
+        onRetry(error, attempt);
+      }
+      const backoffBase = getLimits().retry_backoff_base_ms ?? 200;
+      await delay(backoffBase * attempt);
+    }
+  }
+};
+
+const searchCache = new Map();
+
+const pruneSearchCache = () => {
+  const maxEntries = getLimits().max_search_cache_entries ?? MAX_SEARCH_CACHE_ENTRIES;
+  const now = __timeNowMs();
+  for (const [key, entry] of searchCache) {
+    if (!entry || entry.expiresAt <= now) {
+      searchCache.delete(key);
+    }
+  }
+
+  if (searchCache.size <= maxEntries) {
+    return;
+  }
+
+  const ordered = [...searchCache.entries()].sort((a, b) => (a[1]?.createdAt || 0) - (b[1]?.createdAt || 0));
+  const toRemove = searchCache.size - maxEntries;
+  for (let i = 0; i < toRemove; i += 1) {
+    searchCache.delete(ordered[i][0]);
+  }
+};
+
+const getSearchCache = (queryKey) => {
+  const entry = searchCache.get(queryKey);
+  if (!entry) return null;
+  if (entry.expiresAt <= __timeNowMs()) {
+    searchCache.delete(queryKey);
+    return null;
+  }
+  return entry.value;
+};
+
+const setSearchCache = (queryKey, value) => {
+  const ttlMs = getLimits().search_cache_ttl_ms ?? SEARCH_CACHE_TTL_MS;
+  const now = __timeNowMs();
+  searchCache.set(queryKey, {
+    value,
+    createdAt: now,
+    expiresAt: now + ttlMs,
+  });
+  pruneSearchCache();
+};
+
+const ensurePlayLocalDirs = async () => {
+  await fs.promises.mkdir(PLAY_DOWNLOADS_DIR, { recursive: true });
+};
+
+const normalizeYoutubeWatchUrl = (value) => {
+  if (!value || typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  const direct = ensureHttpUrl(trimmed);
+  if (direct) return direct;
+
+  if (/^[a-zA-Z0-9_-]{6,}$/.test(trimmed)) {
+    return `https://www.youtube.com/watch?v=${trimmed}`;
+  }
+
+  return null;
+};
+
+const normalizeProviderError = (error, { endpoint, requestId, input, timeoutMessage, fallbackMessage }) => {
+  if (KNOWN_ERROR_CODES.has(error?.code) && error?.message) return error;
+
+  const stderr = String(error?.stderr || '').trim();
+  const stdout = String(error?.stdout || '').trim();
+  const combined = `${stderr}\n${stdout}\n${error?.message || ''}`.trim();
+  const low = combined.toLowerCase();
+
+  if (error?.code === 'ETIMEDOUT') {
+    return createError(ERROR_CODES.TIMEOUT, timeoutMessage, {
+      endpoint,
+      requestId,
+      input: truncateText(input || ''),
+      rawCode: error?.code || null,
+      technical: true,
+    });
+  }
+
+  if (low.includes('no matches found') || low.includes('unsupported url')) {
+    return createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+      endpoint,
+      requestId,
+      input: truncateText(input || ''),
+      cause: truncateText(combined),
+      rawCode: error?.code || null,
+      technical: false,
+    });
+  }
+
+  if (low.includes('sign in to confirm') || low.includes('private video') || low.includes('video unavailable')) {
+    return createError(ERROR_CODES.API, playText('video_unavailable', 'Não foi possível acessar este vídeo agora. Tente outro link.'), {
+      endpoint,
+      requestId,
+      input: truncateText(input || ''),
+      cause: truncateText(combined),
+      rawCode: error?.code || null,
+      technical: false,
+    });
+  }
+
+  if (low.includes('ffmpeg') && low.includes('not found')) {
+    return createError(ERROR_CODES.API, playText('ffmpeg_not_found', 'ffmpeg não encontrado no servidor para processar esta mídia.'), {
+      endpoint,
+      requestId,
+      input: truncateText(input || ''),
+      cause: truncateText(combined),
+      rawCode: error?.code || null,
+      technical: true,
+    });
+  }
+
+  return createError(ERROR_CODES.API, fallbackMessage, {
+    endpoint,
+    requestId,
+    input: truncateText(input || ''),
+    rawCode: error?.code || null,
+    exitCode: error?.exitCode ?? null,
+    signal: error?.signal || null,
+    cause: truncateText(combined || 'unknown'),
+    technical: true,
+  });
+};
+
+const YTMP3_AUDIO_FORMATS = new Set(['mp3', 'm4a', 'flac', 'ogg', 'wav', 'opus']);
+const YTMP3_AUDIO_BITRATES = new Set(['best', '320', '192', '128', '64']);
+const YTMP3_DEFAULT_AUDIO_FORMAT = 'mp3';
+const YTMP3_DEFAULT_AUDIO_BITRATE = '128';
+
+const resolveYtmp3AudioSettings = () => {
+  const executionOptions = getExecutionOptions();
+  const formatOptions = executionOptions?.estrategias_formato || {};
+  const audioExtract = formatOptions.audio_extract && typeof formatOptions.audio_extract === 'object' ? formatOptions.audio_extract : {};
+
+  const extractedFormat = String(audioExtract.format || YTMP3_DEFAULT_AUDIO_FORMAT)
+    .trim()
+    .toLowerCase();
+  const audioFormat = YTMP3_AUDIO_FORMATS.has(extractedFormat) ? extractedFormat : YTMP3_DEFAULT_AUDIO_FORMAT;
+
+  const rawQuality = String(audioExtract.quality || YTMP3_DEFAULT_AUDIO_BITRATE)
+    .trim()
+    .toLowerCase();
+  const mappedQuality = rawQuality === '0' ? 'best' : rawQuality.replace(/k$/i, '');
+  const audioBitrate = YTMP3_AUDIO_BITRATES.has(mappedQuality) ? mappedQuality : YTMP3_DEFAULT_AUDIO_BITRATE;
+
+  return {
+    audioFormat,
+    audioBitrate,
+    audioTrack: 'origin',
+  };
+};
+
+const resolveYtmp3RuntimeOs = () => {
+  const platform = String(os.platform() || '').toLowerCase();
+  if (platform === 'darwin') return 'macos';
+  if (platform === 'win32') return 'windows';
+  if (platform === 'android') return 'android';
+  if (platform === 'linux') return 'linux';
+  return 'windows';
+};
+
+const unwrapApiData = (payload) => {
+  if (payload && typeof payload === 'object' && payload.data && typeof payload.data === 'object') {
+    return payload.data;
+  }
+  return payload;
+};
+
+const normalizeYtmp3StatusPayload = (payload) => {
+  const raw = unwrapApiData(payload);
+  if (!raw || typeof raw !== 'object') {
+    return {
+      status: '',
+      message: null,
+      progress: null,
+      downloadUrl: null,
+      title: null,
+    };
+  }
+
+  return {
+    status: String(raw.status || '')
+      .trim()
+      .toLowerCase(),
+    message: pickFirstString(raw, ['jobError', 'message', 'error']),
+    progress: toNumberOrNull(raw.progress),
+    downloadUrl: resolveHttpUrl(raw.downloadUrl || raw.download_url),
+    title: pickFirstString(raw, ['title', 'name']),
+  };
+};
+
+const buildYtmp3DownloadEndpoint = () => {
+  const baseUrl = ensureHttpUrl(PLAY_YTMP3_API_BASE_URL);
+  if (!baseUrl) {
+    throw createError(ERROR_CODES.API, playText('download_failed', 'Falha ao baixar o arquivo localmente.'), {
+      endpoint: YTDLS_ENDPOINTS.ytmp3Create,
+      cause: `invalid_ytmp3_base_url:${PLAY_YTMP3_API_BASE_URL || 'empty'}`,
+      technical: true,
+    });
+  }
+
+  const endpointUrl = resolveHttpUrl(PLAY_YTMP3_API_DOWNLOAD_PATH, baseUrl);
+  if (!endpointUrl) {
+    throw createError(ERROR_CODES.API, playText('download_failed', 'Falha ao baixar o arquivo localmente.'), {
+      endpoint: YTDLS_ENDPOINTS.ytmp3Create,
+      cause: `invalid_ytmp3_download_path:${PLAY_YTMP3_API_DOWNLOAD_PATH || 'empty'}`,
+      technical: true,
+    });
+  }
+
+  return endpointUrl;
+};
+
+const createYtmp3DownloadTask = async ({ link, type, requestId, audioFormat, audioBitrate, audioTrack, youtubeVideoContainer, videoQuality }) => {
+  const endpointUrl = buildYtmp3DownloadEndpoint();
+
+  const downloadType = type === 'video' ? 'video' : 'audio';
+  const payload = {
+    url: link,
+    os: resolveYtmp3RuntimeOs(),
+    output: {
+      type: downloadType,
+      format: downloadType === 'video' ? youtubeVideoContainer || YTMP3_DEFAULT_VIDEO_CONTAINER : audioFormat || YTMP3_DEFAULT_AUDIO_FORMAT,
+    },
+  };
+
+  if (downloadType === 'video' && videoQuality) {
+    payload.output.quality = `${String(videoQuality).replace(/p$/i, '')}p`;
+  }
+
+  if (downloadType === 'audio') {
+    const audioPayload = {};
+    if (audioBitrate && String(audioBitrate).toLowerCase() !== 'best') {
+      audioPayload.bitrate = `${String(audioBitrate).replace(/k$/i, '')}k`;
+    }
+    if (audioTrack && String(audioTrack).trim() && String(audioTrack).trim().toLowerCase() !== 'origin') {
+      audioPayload.trackId = String(audioTrack).trim();
+    }
+    if (Object.keys(audioPayload).length) {
+      payload.audio = audioPayload;
+    }
+  }
+
+  const response = await httpClient.requestJson({
+    url: endpointUrl,
+    method: 'POST',
+    data: payload,
+    endpoint: YTDLS_ENDPOINTS.ytmp3Create,
+    timeoutMs: Math.min(DOWNLOAD_TIMEOUT_MS, 60000),
+    timeoutMessage: playText('download_timeout', 'Timeout ao baixar o arquivo.'),
+    fallbackMessage: playText('download_failed', 'Falha ao baixar o arquivo localmente.'),
+  });
+  const normalized = unwrapApiData(response);
+  const statusUrl = resolveHttpUrl(normalized?.statusUrl || normalized?.status_url, endpointUrl);
+
+  if (!statusUrl) {
+    throw createError(ERROR_CODES.API, playText('download_failed', 'Falha ao baixar o arquivo localmente.'), {
+      endpoint: YTDLS_ENDPOINTS.ytmp3Create,
+      requestId,
+      input: truncateText(link || ''),
+      cause: truncateText(JSON.stringify(normalized || {})),
+      technical: true,
+    });
+  }
+
+  return {
+    statusUrl,
+    title: pickFirstString(normalized, ['title', 'name']),
+  };
+};
+
+const pollYtmp3UntilReady = async ({ statusUrl, requestId, input }) => {
+  const timeoutMs = Math.max(15000, DOWNLOAD_TIMEOUT_MS);
+  const pollIntervalMs = Math.max(500, Number(getLimits().ytmp3_poll_interval_ms ?? PLAY_YTMP3_POLL_INTERVAL_MS));
+  const startedAt = __timeNowMs();
+
+  while (true) {
+    const elapsedMs = __timeNowMs() - startedAt;
+    if (elapsedMs >= timeoutMs) {
+      throw createError(ERROR_CODES.TIMEOUT, playText('download_timeout', 'Timeout ao baixar o arquivo.'), {
+        endpoint: YTDLS_ENDPOINTS.ytmp3Poll,
+        requestId,
+        input: truncateText(input || ''),
+        statusUrl: truncateText(statusUrl, 400),
+        technical: true,
+      });
+    }
+
+    const payload = await httpClient.requestJson({
+      url: statusUrl,
+      method: 'GET',
+      endpoint: YTDLS_ENDPOINTS.ytmp3Poll,
+      timeoutMs: Math.max(1000, Math.min(15000, timeoutMs - elapsedMs)),
+      timeoutMessage: playText('download_timeout', 'Timeout ao baixar o arquivo.'),
+      fallbackMessage: playText('download_failed', 'Falha ao baixar o arquivo localmente.'),
+    });
+    const status = normalizeYtmp3StatusPayload(payload);
+
+    if (status.downloadUrl && (!status.status || status.status === 'completed')) {
+      return {
+        downloadUrl: status.downloadUrl,
+        title: status.title,
+      };
+    }
+
+    if (status.status === 'completed') {
+      if (!status.downloadUrl) {
+        throw createError(ERROR_CODES.API, playText('download_failed', 'Falha ao baixar o arquivo localmente.'), {
+          endpoint: YTDLS_ENDPOINTS.ytmp3Poll,
+          requestId,
+          input: truncateText(input || ''),
+          status: status.status,
+          cause: status.message || 'missing_download_url',
+          technical: true,
+        });
+      }
+
+      return {
+        downloadUrl: status.downloadUrl,
+        title: status.title,
+      };
+    }
+
+    if (status.status === 'failed' || status.status === 'error' || status.status === 'not_found') {
+      throw createError(ERROR_CODES.API, playText('download_failed', 'Falha ao baixar o arquivo localmente.'), {
+        endpoint: YTDLS_ENDPOINTS.ytmp3Poll,
+        requestId,
+        input: truncateText(input || ''),
+        status: status.status,
+        cause: truncateText(status.message || 'ytmp3_failed'),
+        technical: true,
+      });
+    }
+
+    await delay(pollIntervalMs);
+  }
+};
+
+const YTMP3_VIDEO_CONTAINERS = new Set(['mp4', 'webm', 'mkv']);
+const YTMP3_DEFAULT_VIDEO_CONTAINER = 'mp4';
+
+const resolveYtmp3VideoSettings = () => {
+  const executionOptions = getExecutionOptions();
+  const formatOptions = executionOptions?.estrategias_formato || {};
+  const mergeOutputFormat = String(formatOptions.video_merge_output_format || YTMP3_DEFAULT_VIDEO_CONTAINER)
+    .trim()
+    .toLowerCase();
+  const youtubeVideoContainer = YTMP3_VIDEO_CONTAINERS.has(mergeOutputFormat) ? mergeOutputFormat : YTMP3_DEFAULT_VIDEO_CONTAINER;
+  const rawQuality = String(PLAY_YTMP3_VIDEO_DEFAULT_QUALITY || '720')
+    .trim()
+    .replace(/p$/i, '');
+  const videoQuality = /^\d{3,4}$/.test(rawQuality) ? rawQuality : '720';
+
+  return {
+    youtubeVideoContainer,
+    videoQuality,
+  };
+};
+
+const isYtmp3PrimaryEligible = ({ type, link }) => PLAY_YTMP3_ENABLED && (type === 'audio' || type === 'video') && isYouTubeUrl(link);
+
+const requestYtmp3DownloadToFile = async ({ link, type, requestId, basePath }) => {
+  const audioSettings = resolveYtmp3AudioSettings();
+  const videoSettings = resolveYtmp3VideoSettings();
+  const targetExt = type === 'video' ? videoSettings.youtubeVideoContainer : audioSettings.audioFormat || YTMP3_DEFAULT_AUDIO_FORMAT;
+  const targetPath = `${basePath}.${targetExt}`;
+
+  return runWithPlayProcessSlot(
+    async () => {
+      const task = await createYtmp3DownloadTask({
+        link,
+        type,
+        requestId,
+        audioFormat: audioSettings.audioFormat,
+        audioBitrate: audioSettings.audioBitrate,
+        audioTrack: audioSettings.audioTrack,
+        youtubeVideoContainer: videoSettings.youtubeVideoContainer,
+        videoQuality: videoSettings.videoQuality,
+      });
+
+      const ready = await pollYtmp3UntilReady({
+        statusUrl: task.statusUrl,
+        requestId,
+        input: link,
+      });
+
+      const downloaded = await httpClient.requestFile({
+        url: ready.downloadUrl,
+        filePath: targetPath,
+        endpoint: YTDLS_ENDPOINTS.ytmp3Download,
+        timeoutMs: DOWNLOAD_TIMEOUT_MS,
+        timeoutMessage: playText('download_timeout', 'Timeout ao baixar o arquivo.'),
+        fallbackMessage: playText('download_failed', 'Falha ao baixar o arquivo localmente.'),
+      });
+
+      return {
+        filePath: targetPath,
+        bytes: downloaded.bytes,
+        contentType: resolveMediaMimeType(type, downloaded.contentType),
+        mediaType: type,
+      };
+    },
+    {
+      endpoint: YTDLS_ENDPOINTS.ytmp3Create,
+      command: 'ytmp3',
+    },
+  );
+};
+
+const buildYtmp3SearchEndpoint = () => {
+  const baseUrl = ensureHttpUrl(PLAY_YTMP3_SEARCH_BASE_URL);
+  if (!baseUrl) {
+    throw createError(ERROR_CODES.API, playText('search_failed', 'Não foi possível buscar o vídeo agora.'), {
+      endpoint: YTDLS_ENDPOINTS.ytmp3Search,
+      cause: `invalid_ytmp3_search_base_url:${PLAY_YTMP3_SEARCH_BASE_URL || 'empty'}`,
+      technical: true,
+    });
+  }
+
+  const endpointUrl = resolveHttpUrl(PLAY_YTMP3_SEARCH_PATH, baseUrl);
+  if (!endpointUrl) {
+    throw createError(ERROR_CODES.API, playText('search_failed', 'Não foi possível buscar o vídeo agora.'), {
+      endpoint: YTDLS_ENDPOINTS.ytmp3Search,
+      cause: `invalid_ytmp3_search_path:${PLAY_YTMP3_SEARCH_PATH || 'empty'}`,
+      technical: true,
+    });
+  }
+
+  return endpointUrl;
+};
+
+const extractYoutubeVideoIdFromUrl = (value) => {
+  const normalized = ensureHttpUrl(value);
+  if (!normalized) return null;
+
+  try {
+    const parsed = new URL(normalized);
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname === 'youtu.be' || hostname.endsWith('.youtu.be')) {
+      const candidate = parsed.pathname.replace(/^\/+/, '').split('/')[0];
+      if (candidate) return candidate;
+    }
+
+    const v = parsed.searchParams.get('v');
+    if (v) return v;
+
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    if (parts.length >= 2 && ['shorts', 'embed', 'live', 'v'].includes(parts[0].toLowerCase())) {
+      return parts[1];
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+};
+
+const normalizeYtmp3SearchItem = (item) => {
+  if (!item || typeof item !== 'object') return null;
+  if (item.type && item.type !== 'stream') return null;
+
+  const url = normalizeYoutubeWatchUrl(item.id || item.url || item.webpage_url);
+  if (!url || !isYouTubeUrl(url)) return null;
+
+  const thumbnailUrl = resolveHttpUrl(item.thumbnailUrl || item.thumbnail);
+
+  return {
+    id: extractYoutubeVideoIdFromUrl(url) || pickFirstString(item, ['id', 'videoId', 'video_id']),
+    title: pickFirstString(item, ['title', 'name']) || 'Sem título',
+    channel: pickFirstString(item, ['uploaderName', 'channel', 'author', 'uploader']),
+    uploader: pickFirstString(item, ['uploaderName', 'uploader', 'channel', 'author']),
+    duration: toNumberOrNull(item.duration) ?? item.duration ?? null,
+    thumbnail: thumbnailUrl || null,
+    thumbnails: thumbnailUrl ? [{ url: thumbnailUrl }] : [],
+    url,
+    webpage_url: url,
+  };
+};
+
+const fetchYouTubeOEmbedInfo = async (url) => {
+  const oembedEndpoint = 'https://www.youtube.com/oembed';
+  const response = await httpClient.requestJson({
+    url: oembedEndpoint,
+    method: 'GET',
+    data: {
+      url,
+      format: 'json',
+    },
+    endpoint: YTDLS_ENDPOINTS.ytmp3Metadata,
+    timeoutMs: Math.min(15000, MEDIA_INFO_TIMEOUT_MS),
+    timeoutMessage: playText('search_timeout', 'Timeout ao buscar metadados do vídeo.'),
+    fallbackMessage: playText('search_failed', 'Não foi possível buscar o vídeo agora.'),
+  });
+
+  const normalizedUrl = normalizeYoutubeWatchUrl(url);
+  const thumbnailUrl = resolveHttpUrl(response?.thumbnail_url);
+
+  return {
+    id: extractYoutubeVideoIdFromUrl(normalizedUrl),
+    title: pickFirstString(response, ['title']) || 'Sem título',
+    channel: pickFirstString(response, ['author_name']),
+    uploader: pickFirstString(response, ['author_name']),
+    duration: null,
+    thumbnail: thumbnailUrl || null,
+    thumbnails: thumbnailUrl ? [{ url: thumbnailUrl }] : [],
+    url: normalizedUrl,
+    webpage_url: normalizedUrl,
+  };
+};
+
+const fetchSearchResult = async (query) => {
+  const normalized = typeof query === 'string' ? query.trim() : '';
+  if (!normalized) {
+    throw createError(ERROR_CODES.INVALID_INPUT, playText('search_invalid_input', 'Você precisa informar um link do YouTube ou termo de busca.'), {
+      endpoint: YTDLS_ENDPOINTS.search,
+      technical: false,
+    });
+  }
+
+  const cacheKey = normalized.toLowerCase();
+  const cached = getSearchCache(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const endpoint = YTDLS_ENDPOINTS.search;
+  const isUrlLookup = /^https?:\/\//i.test(normalized);
+  const maxSearchResults = getLimits().max_search_results ?? MAX_SEARCH_RESULTS;
+  const normalizedUrlLookup = isUrlLookup ? normalizeYoutubeWatchUrl(normalized) : null;
+
+  const payload = await retryAsync(
+    async () => {
+      let normalizedEntries = [];
+
+      if (isUrlLookup) {
+        if (!normalizedUrlLookup || !isYouTubeUrl(normalizedUrlLookup)) {
+          throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+            endpoint,
+            technical: false,
+          });
+        }
+
+        try {
+          const oembedInfo = await fetchYouTubeOEmbedInfo(normalizedUrlLookup);
+          normalizedEntries = [oembedInfo].filter(Boolean);
+        } catch {
+          normalizedEntries = [
+            {
+              id: extractYoutubeVideoIdFromUrl(normalizedUrlLookup),
+              title: 'Sem título',
+              channel: null,
+              uploader: null,
+              duration: null,
+              thumbnail: null,
+              thumbnails: [],
+              url: normalizedUrlLookup,
+              webpage_url: normalizedUrlLookup,
+            },
+          ];
+        }
+      } else {
+        const searchEndpoint = buildYtmp3SearchEndpoint();
+        const response = await httpClient.requestJson({
+          url: searchEndpoint,
+          method: 'GET',
+          data: {
+            q: normalized,
+            limit: maxSearchResults,
+          },
+          endpoint: YTDLS_ENDPOINTS.ytmp3Search,
+          timeoutMs: Math.min(20000, MEDIA_INFO_TIMEOUT_MS),
+          timeoutMessage: playText('search_timeout', 'Timeout ao buscar metadados do vídeo.'),
+          fallbackMessage: playText('search_failed', 'Não foi possível buscar o vídeo agora.'),
+        });
+
+        const raw = unwrapApiData(response);
+        const items = Array.isArray(raw?.items) ? raw.items : [];
+        normalizedEntries = items.map((item) => normalizeYtmp3SearchItem(item)).filter((entry) => entry?.url);
+      }
+
+      const info = normalizedEntries[0] || null;
+
+      if (!info?.url) {
+        throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+          endpoint,
+          technical: false,
+        });
+      }
+
+      return {
+        sucesso: true,
+        resultado: info,
+        resultados: normalizedEntries,
+      };
+    },
+    {
+      retries: getLimits().search_retry_count ?? 1,
+      shouldRetry: isTransientError,
+      onRetry: (error, attempt) => {
+        logger.warn('Play busca local: retry acionado.', {
+          endpoint,
+          attempt,
+          code: error?.code,
+          status: error?.meta?.status || null,
+        });
+      },
+    },
+  );
+
+  setSearchCache(cacheKey, payload);
+  return payload;
+};
+
+const resolveYoutubeLink = async (query) => {
+  const normalized = query ? query.trim() : '';
+
+  if (!normalized) {
+    throw createError(ERROR_CODES.INVALID_INPUT, playText('search_invalid_input', 'Você precisa informar um link do YouTube ou termo de busca.'), {
+      endpoint: YTDLS_ENDPOINTS.search,
+      technical: false,
+    });
+  }
+
+  if (/^https?:\/\//i.test(normalized)) {
+    const direct = normalizeYoutubeWatchUrl(normalized);
+    if (!direct || !isYouTubeUrl(direct)) {
+      throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+        endpoint: YTDLS_ENDPOINTS.search,
+        technical: false,
+      });
+    }
+    return direct;
+  }
+
+  const searchResult = await fetchSearchResult(normalized);
+  if (!searchResult?.resultado?.url) {
+    throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+      endpoint: YTDLS_ENDPOINTS.search,
+      technical: false,
+    });
+  }
+
+  return searchResult.resultado.url;
+};
+
+const extractCandidateUrlsFromSearchResult = (searchResult) => {
+  const urls = [];
+  const seen = new Set();
+
+  const pushUrl = (value) => {
+    const url = ensureHttpUrl(value);
+    if (!url) return;
+    if (seen.has(url)) return;
+    seen.add(url);
+    urls.push(url);
+  };
+
+  if (searchResult?.resultado?.url) {
+    pushUrl(searchResult.resultado.url);
+  }
+
+  if (Array.isArray(searchResult?.resultados)) {
+    for (const item of searchResult.resultados) {
+      pushUrl(item?.url);
+    }
+  }
+
+  return urls;
+};
+
+const resolveYoutubeCandidates = async (query) => {
+  const normalized = query ? query.trim() : '';
+
+  if (!normalized) {
+    throw createError(ERROR_CODES.INVALID_INPUT, playText('search_invalid_input', 'Você precisa informar um link do YouTube ou termo de busca.'), {
+      endpoint: YTDLS_ENDPOINTS.search,
+      technical: false,
+    });
+  }
+
+  if (/^https?:\/\//i.test(normalized)) {
+    const direct = normalizeYoutubeWatchUrl(normalized);
+    if (!direct || !isYouTubeUrl(direct)) {
+      throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+        endpoint: YTDLS_ENDPOINTS.search,
+        technical: false,
+      });
+    }
+    return [direct];
+  }
+
+  const searchResult = await fetchSearchResult(normalized);
+  const urls = extractCandidateUrlsFromSearchResult(searchResult);
+
+  if (!urls.length) {
+    throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+      endpoint: YTDLS_ENDPOINTS.search,
+      technical: false,
+    });
+  }
+
+  return urls;
+};
+
+const isYouTubeBotCheckCause = (error) => {
+  const cause = String(error?.meta?.cause || '').toLowerCase();
+  const message = String(error?.message || '').toLowerCase();
+  return cause.includes('sign in to confirm') || message.includes('sign in to confirm');
+};
+
+const buildYouTubeBotCheckUserMessage = () => {
+  return getPlayText('anti_bot_without_cookies', 'YouTube solicitou verificação anti-bot no provedor de mídia. Tente novamente em alguns minutos.');
+};
+
+const fetchVideoInfo = async (query, fallback) => {
+  const tryQuery = async (value) => {
+    if (!value) return null;
+    try {
+      const result = await fetchSearchResult(value);
+      if (!result?.sucesso || !result?.resultado) return null;
+      return result.resultado;
+    } catch {
+      return null;
+    }
+  };
+
+  const first = await tryQuery(query);
+  if (first) return first;
+
+  const normalizedQuery = typeof query === 'string' ? query.trim().toLowerCase() : '';
+  const normalizedFallback = typeof fallback === 'string' ? fallback.trim().toLowerCase() : '';
+  if (normalizedFallback && normalizedFallback !== normalizedQuery) {
+    return tryQuery(fallback);
+  }
+
+  return null;
+};
+
+const fetchQueueStatus = async (requestId) => {
+  void requestId;
+  return null;
+};
+
+const inferMimeFromFilePath = (filePath, type) => {
+  const ext = path.extname(filePath || '').toLowerCase();
+  if (type === 'audio') {
+    if (ext === '.m4a' || ext === '.mp4') return 'audio/mp4';
+    if (ext === '.ogg' || ext === '.opus') return 'audio/ogg';
+    if (ext === '.wav') return 'audio/wav';
+    return TYPE_CONFIG.audio.mimeFallback;
+  }
+
+  if (type === 'video') {
+    if (ext === '.webm') return 'video/webm';
+    return TYPE_CONFIG.video.mimeFallback;
+  }
+
+  return 'application/octet-stream';
+};
+
+const findDownloadedFileByBase = async (basePath, preferredExt) => {
+  const dir = path.dirname(basePath);
+  const baseName = path.basename(basePath);
+
+  let entries = [];
+  try {
+    entries = await fs.promises.readdir(dir);
+  } catch {
+    return null;
+  }
+
+  const candidates = entries.filter((name) => name.startsWith(`${baseName}.`));
+  if (!candidates.length) return null;
+
+  if (preferredExt) {
+    const preferred = candidates.find((name) => path.extname(name).toLowerCase() === `.${preferredExt.toLowerCase()}`);
+    if (preferred) {
+      return path.join(dir, preferred);
+    }
+  }
+
+  const stats = await Promise.all(
+    candidates.map(async (name) => {
+      const fullPath = path.join(dir, name);
+      try {
+        const stat = await fs.promises.stat(fullPath);
+        return { fullPath, mtimeMs: stat.mtimeMs };
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  const existing = stats.filter(Boolean);
+  if (!existing.length) return null;
+
+  existing.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return existing[0].fullPath;
+};
+
+const cleanupDownloadedArtifacts = async (basePath) => {
+  const dir = path.dirname(basePath);
+  const baseName = path.basename(basePath);
+
+  let entries = [];
+  try {
+    entries = await fs.promises.readdir(dir);
+  } catch {
+    return;
+  }
+
+  const targets = entries.filter((name) => name.startsWith(`${baseName}.`));
+  await Promise.allSettled(targets.map((name) => safeUnlink(path.join(dir, name))));
+};
+
+const requestDownloadToFile = async (link, type, requestId) => {
+  const endpoint = YTDLS_ENDPOINTS.ytmp3Download;
+  const safeId = String(requestId || 'req')
+    .replace(/[^a-z0-9-_]+/gi, '')
+    .slice(0, 48);
+  const basePath = path.join(PLAY_DOWNLOADS_DIR, `play-${safeId}-${__timeNowMs()}`);
+  let filePath = null;
+  let providerResult = null;
+
+  try {
+    await ensurePlayLocalDirs();
+
+    if (!isYtmp3PrimaryEligible({ type, link })) {
+      throw createError(ERROR_CODES.NOT_FOUND, playText('search_not_found', 'Nenhum resultado encontrado para a busca.'), {
+        endpoint: YTDLS_ENDPOINTS.ytmp3Download,
+        requestId,
+        input: truncateText(link || ''),
+        technical: false,
+      });
+    }
+
+    providerResult = await requestYtmp3DownloadToFile({
+      link,
+      type,
+      requestId,
+      basePath,
+    });
+
+    logger.info('Play download: ytmp3 concluído.', {
+      requestId,
+      endpoint: YTDLS_ENDPOINTS.ytmp3Download,
+      type,
+      bytes: providerResult?.bytes || 0,
+    });
+
+    filePath = providerResult?.filePath || (await findDownloadedFileByBase(basePath, type === 'audio' ? 'mp3' : 'mp4'));
+    if (!filePath) {
+      throw createError(ERROR_CODES.API, playText('download_file_not_found', 'Não foi possível localizar o arquivo baixado.'), {
+        endpoint,
+        requestId,
+        technical: true,
+      });
+    }
+
+    let stat = await fs.promises.stat(filePath);
+    let finalBytes = Number(stat?.size || 0);
+    let finalMimeType = providerResult?.contentType || inferMimeFromFilePath(filePath, type);
+    let finalMediaType = providerResult?.mediaType || type;
+
+    if (finalBytes <= 0) {
+      throw createError(ERROR_CODES.API, playText('download_invalid_media', 'Falha ao baixar mídia válida.'), {
+        endpoint,
+        requestId,
+        filePath,
+        technical: true,
+      });
+    }
+
+    if (finalBytes > MAX_MEDIA_BYTES) {
+      throw createError(ERROR_CODES.TOO_BIG, playText('media_too_big', `O arquivo excede o limite permitido de ${MAX_MEDIA_MB_LABEL} MB.`, { max_mb: MAX_MEDIA_MB_LABEL }), {
+        endpoint,
+        requestId,
+        bytes: finalBytes,
+        technical: false,
+      });
+    }
+
+    if (type === 'video') {
+      const streamInfo = await probeVideoStreams(filePath, requestId, endpoint);
+
+      if (!streamInfo.hasVideo) {
+        if (streamInfo.hasAudio) {
+          finalMediaType = 'audio';
+          finalMimeType = inferMimeFromFilePath(filePath, 'audio');
+
+          logger.warn('Play vídeo: fonte retornou somente áudio, fallback ativado.', {
+            requestId,
+            endpoint,
+            bytes: finalBytes,
+            audioCodec: streamInfo.audioCodec || null,
+          });
+        } else {
+          throw createError(ERROR_CODES.API, playText('video_without_streams', 'Não foi possível enviar como vídeo: a mídia não possui faixa de vídeo nem áudio.'), {
+            endpoint,
+            requestId,
+            hasAudio: streamInfo.hasAudio,
+            videoCodec: streamInfo.videoCodec,
+            audioCodec: streamInfo.audioCodec,
+            technical: true,
+          });
+        }
+      }
+
+      if (finalMediaType === 'video') {
+        if (VIDEO_FORCE_TRANSCODE || streamInfo.videoCodec !== 'h264' || (streamInfo.hasAudio && streamInfo.audioCodec !== 'aac')) {
+          finalBytes = await transcodeVideoForWhatsapp(filePath, requestId, endpoint);
+          finalMimeType = TYPE_CONFIG.video.mimeFallback;
+          logger.info('Play vídeo normalizado para compatibilidade.', {
+            requestId,
+            endpoint,
+            originalVideoCodec: streamInfo.videoCodec || null,
+            originalAudioCodec: streamInfo.audioCodec || null,
+            bytes: finalBytes,
+          });
+        }
+      }
+    }
+
+    stat = await fs.promises.stat(filePath);
+    finalBytes = Number(stat?.size || finalBytes || 0);
+
+    return {
+      filePath,
+      contentType: finalMimeType || resolveMediaMimeType(finalMediaType, null),
+      bytes: finalBytes,
+      mediaType: finalMediaType,
+    };
+  } catch (error) {
+    await cleanupDownloadedArtifacts(basePath);
+    const normalized =
+      KNOWN_ERROR_CODES.has(error?.code) && error?.message
+        ? error
+        : normalizeProviderError(error, {
+            endpoint,
+            requestId,
+            input: link,
+            timeoutMessage: playText('download_timeout', 'Timeout ao baixar o arquivo.'),
+            fallbackMessage: playText('download_failed', 'Falha ao baixar o arquivo localmente.'),
+          });
+    throw withErrorMeta(normalized, { endpoint: normalized?.meta?.endpoint || endpoint, filePath, provider: 'ytmp3' });
+  }
+};
+
+const fetchThumbnailBuffer = async (url) =>
+  retryAsync(
+    () =>
+      httpClient.requestBuffer({
+        url,
+        timeoutMs: getLimits().thumbnail_timeout_ms ?? THUMBNAIL_TIMEOUT_MS,
+        maxBytes: getLimits().max_thumb_bytes ?? MAX_THUMB_BYTES,
+        endpoint: YTDLS_ENDPOINTS.thumbnail,
+      }),
+    {
+      retries: getLimits().thumbnail_retry_count ?? 1,
+      shouldRetry: isTransientError,
+      onRetry: (error, attempt) => {
+        logger.warn('Play thumbnail: retry acionado.', {
+          endpoint: YTDLS_ENDPOINTS.thumbnail,
+          attempt,
+          code: error?.code,
+          status: error?.meta?.status || null,
+        });
+      },
+    },
+  );
+
+const playMediaClient = {
+  resolveYoutubeLink,
+  resolveYoutubeCandidates,
+  fetchVideoInfo,
+  fetchQueueStatus,
+  requestDownloadToFile,
+  fetchThumbnailBuffer,
+};
+
+const formatters = {
+  formatNumber,
+  formatDuration,
+  formatVideoInfo,
+  getThumbnailUrl,
+  buildQueueStatusText,
+  buildReadyCaption,
+};
+
+const fileUtils = {
+  buildTempFilePath,
+  safeUnlink,
+};
+
+export const __playMediaClientTestUtils = {
+  extractCandidateUrlsFromSearchResult,
+  isYtmp3PrimaryEligible,
+  isYouTubeBotCheckCause,
+  buildYouTubeBotCheckUserMessage,
+  getProcessLimiterStats: () => playProcessLimiter.stats(),
+};
+
+export { createError, withErrorMeta, normalizePlayError, truncateText, playMediaClient, formatters, fileUtils, isYouTubeBotCheckCause, buildYouTubeBotCheckUserMessage };