feat(downloads): add custom download formats

index.html

@@ -5108,7 +5108,6 @@
                                     <select id="download-quality-setting">
                                         <option value="HI_RES_LOSSLESS">Hi-Res FLAC (24-bit)</option>
                                         <option value="LOSSLESS">FLAC (Lossless)</option>
-                                        <option value="MP3_320">MP3 320kbps</option>
                                         <option value="HIGH">AAC 320kbps</option>
                                         <option value="LOW">AAC 96kbps</option>
                                     </select>

js/api.js

@@ -11,9 +11,10 @@ import { APICache } from './cache.js';
 import { addMetadataToAudio, prefetchMetadataObjects } from './metadata.js';
 import { DashDownloader } from './dash-downloader.js';
 import { HlsDownloader } from './hls-downloader.js';
-import { encodeToMp3, MP3EncodingError } from './mp3-encoder.js';
+import { MP3EncodingError } from './mp3-encoder.js';
-import { ffmpeg, loadFfmpeg } from './ffmpeg.js';
+import { ffmpeg, loadFfmpeg, FfmpegError } from './ffmpeg.js';
 import { rebuildFlacWithoutMetadata } from './metadata.flac.js';
+import { isCustomFormat, getCustomFormat, transcodeWithCustomFormat } from './customFormats.ts';
 
 export const DASH_MANIFEST_UNAVAILABLE_CODE = 'DASH_MANIFEST_UNAVAILABLE';
 const TIDAL_V2_TOKEN = 'txNoH4kkV41MfH25';
@@ -1294,8 +1295,8 @@ export class LosslessAPI {
         const isVideo = track?.type === 'video';
 
         try {
-            // MP3_320 is not a native TIDAL quality, we download LOSSLESS and convert
+            // Custom FFMPEG formats are not native TIDAL qualities; download LOSSLESS and transcode
-            const downloadQuality = quality === 'MP3_320' ? 'LOSSLESS' : quality;
+            const downloadQuality = isCustomFormat(quality) ? 'LOSSLESS' : quality;
 
             let lookup;
             if (isVideo) {
@@ -1416,18 +1417,21 @@ export class LosslessAPI {
             }
 
             if (!isVideo) {
-                // Convert to MP3 320kbps if requested
+                // Transcode to custom format if requested
-                if (quality === 'MP3_320') {
+                if (isCustomFormat(quality)) {
-                    try {
+                    const format = getCustomFormat(quality);
-                        blob = await encodeToMp3(blob, onProgress, options.signal);
+                    if (format) {
-                    } catch (encodingError) {
+                        try {
-                        if (onProgress) {
+                            blob = await transcodeWithCustomFormat(blob, format, onProgress, options.signal);
-                            onProgress({
+                        } catch (encodingError) {
-                                stage: 'error',
+                            if (onProgress) {
-                                message: `Encoding failed: ${encodingError.message}`,
+                                onProgress({
-                            });
+                                    stage: 'error',
+                                    message: `Encoding failed: ${encodingError.message}`,
+                                });
+                            }
+                            throw encodingError;
                         }
-                        throw encodingError;
                     }
                 }
 
@@ -1510,7 +1514,11 @@ export class LosslessAPI {
                 throw error;
             }
             console.error('Download failed:', error);
-            if (error instanceof MP3EncodingError || error.code === 'MP3_ENCODING_FAILED') {
+            if (
+                error instanceof MP3EncodingError ||
+                error instanceof FfmpegError ||
+                error.code === 'MP3_ENCODING_FAILED'
+            ) {
                 throw error;
             }
             if (error.message === RATE_LIMIT_ERROR_MESSAGE) {

js/customFormats.ts

@@ -0,0 +1,148 @@
+import { ffmpeg } from './ffmpeg';
+
+export interface ProgressEvent {
+    stage?: string;
+    message?: string;
+    progress?: number;
+    receivedBytes?: number;
+    totalBytes?: number;
+}
+
+export interface CustomFormat {
+    /** Human-readable label shown in the UI */
+    displayName: string;
+    /** Internal identifier, must start with `FFMPEG_` */
+    internalName: string;
+    /** Arguments passed to ffmpeg (excluding input/output file args) */
+    ffmpegArgs: string[];
+    /** Output filename used when calling ffmpeg */
+    outputFilename: string;
+    /** MIME type of the encoded output */
+    outputMime: string;
+    /** File extension of the encoded output */
+    extension: string;
+    /** Category label used for grouping in the UI (e.g. 'MP3', 'OGG', 'AAC') */
+    category: string;
+}
+
+export const customFormats: CustomFormat[] = [
+    {
+        displayName: 'MP3 320kbps',
+        internalName: 'FFMPEG_MP3_320',
+        ffmpegArgs: ['-map_metadata', '-1', '-c:a', 'libmp3lame', '-b:a', '320k', '-ar', '44100'],
+        outputFilename: 'output.mp3',
+        outputMime: 'audio/mpeg',
+        extension: 'mp3',
+        category: 'MP3',
+    },
+    {
+        displayName: 'MP3 256kbps',
+        internalName: 'FFMPEG_MP3_256',
+        ffmpegArgs: ['-map_metadata', '-1', '-c:a', 'libmp3lame', '-b:a', '256k', '-ar', '44100'],
+        outputFilename: 'output.mp3',
+        outputMime: 'audio/mpeg',
+        extension: 'mp3',
+        category: 'MP3',
+    },
+    {
+        displayName: 'MP3 128kbps',
+        internalName: 'FFMPEG_MP3_128',
+        ffmpegArgs: ['-map_metadata', '-1', '-c:a', 'libmp3lame', '-b:a', '128k', '-ar', '44100'],
+        outputFilename: 'output.mp3',
+        outputMime: 'audio/mpeg',
+        extension: 'mp3',
+        category: 'MP3',
+    },
+    {
+        displayName: 'OGG 320kbps',
+        internalName: 'FFMPEG_OGG_320',
+        ffmpegArgs: [
+            '-map_metadata',
+            '-1',
+            '-c:a',
+            'libvorbis',
+            '-b:a',
+            '320k',
+            '-minrate',
+            '320k',
+            '-maxrate',
+            '320k',
+        ],
+        outputFilename: 'output.ogg',
+        outputMime: 'audio/ogg',
+        extension: 'ogg',
+        category: 'OGG',
+    },
+    {
+        displayName: 'OGG 256kbps',
+        internalName: 'FFMPEG_OGG_256',
+        ffmpegArgs: [
+            '-map_metadata',
+            '-1',
+            '-c:a',
+            'libvorbis',
+            '-b:a',
+            '256k',
+            '-minrate',
+            '256k',
+            '-maxrate',
+            '256k',
+        ],
+        outputFilename: 'output.ogg',
+        outputMime: 'audio/ogg',
+        extension: 'ogg',
+        category: 'OGG',
+    },
+    {
+        displayName: 'OGG 128kbps',
+        internalName: 'FFMPEG_OGG_128',
+        ffmpegArgs: [
+            '-map_metadata',
+            '-1',
+            '-c:a',
+            'libvorbis',
+            '-b:a',
+            '128k',
+            '-minrate',
+            '128k',
+            '-maxrate',
+            '128k',
+        ],
+        outputFilename: 'output.ogg',
+        outputMime: 'audio/ogg',
+        extension: 'ogg',
+        category: 'OGG',
+    },
+    {
+        displayName: 'AAC 256kbps',
+        internalName: 'FFMPEG_AAC_256',
+        ffmpegArgs: ['-map_metadata', '-1', '-c:a', 'aac', '-b:a', '256k'],
+        outputFilename: 'output.m4a',
+        outputMime: 'audio/mp4',
+        extension: 'm4a',
+        category: 'AAC',
+    },
+];
+
+/** Returns true if the quality string identifies a known custom ffmpeg-transcoded format */
+export function isCustomFormat(quality: string): boolean {
+    return getCustomFormat(quality) !== undefined;
+}
+
+/** Looks up a custom format by its internal name, or returns undefined */
+export function getCustomFormat(internalName: string): CustomFormat | undefined {
+    return customFormats.find((f) => f.internalName === internalName);
+}
+
+/**
+ * Transcodes an audio blob using the specified custom format via ffmpeg.
+ * Throws if ffmpeg fails during transcoding.
+ */
+export async function transcodeWithCustomFormat(
+    audioBlob: Blob,
+    format: CustomFormat,
+    onProgress: ((progress: ProgressEvent) => void) | null = null,
+    signal: AbortSignal | null = null
+): Promise<Blob> {
+    return ffmpeg(audioBlob, { args: format.ffmpegArgs }, format.outputFilename, format.outputMime, onProgress, signal);
+}

js/downloads.js

@@ -16,8 +16,8 @@ import { addMetadataToAudio, prefetchMetadataObjects } from './metadata.js';
 import { rebuildFlacWithoutMetadata } from './metadata.flac.js';
 import { DashDownloader } from './dash-downloader.js';
 import { generateM3U, generateM3U8, generateCUE, generateNFO, generateJSON } from './playlist-generator.js';
-import { encodeToMp3 } from './mp3-encoder.js';
 import { ffmpeg, loadFfmpeg } from './ffmpeg.js';
+import { isCustomFormat, getCustomFormat, transcodeWithCustomFormat } from './customFormats.ts';
 
 const downloadTasks = new Map();
 const bulkDownloadTasks = new Map();
@@ -298,8 +298,8 @@ async function downloadTrackBlob(
         artist: track.artist || (track.artists && track.artists.length > 0 ? track.artists[0] : null),
     };
 
-    // MP3_320 is not a native TIDAL quality, we download LOSSLESS and convert
+    // Custom FFMPEG formats are not native TIDAL qualities; download LOSSLESS and transcode
-    const downloadQuality = quality === 'MP3_320' ? 'LOSSLESS' : quality;
+    const downloadQuality = isCustomFormat(quality) ? 'LOSSLESS' : quality;
 
     try {
         const fullTrack = await api.getTrackMetadata(track.id);
@@ -379,9 +379,12 @@ async function downloadTrackBlob(
         blob = await response.blob();
     }
 
-    // Convert to MP3 320kbps if requested
+    // Transcode to custom format if requested
-    if (quality === 'MP3_320') {
+    if (isCustomFormat(quality)) {
-        blob = await encodeToMp3(blob, onProgress || (() => undefined), signal);
+        const format = getCustomFormat(quality);
+        if (format) {
+            blob = await transcodeWithCustomFormat(blob, format, onProgress || (() => undefined), signal);
+        }
     }
 
     if (quality.endsWith('LOSSLESS')) {

js/settings.js

@@ -42,6 +42,7 @@ import { db } from './db.js';
 import { authManager } from './accounts/auth.js';
 import { syncManager } from './accounts/pocketbase.js';
 import { saveFirebaseConfig, clearFirebaseConfig } from './accounts/config.js';
+import { customFormats } from './customFormats.ts';
 
 export function initializeSettings(scrobbler, player, api, ui) {
     // Restore last active settings tab
@@ -800,6 +801,63 @@ export function initializeSettings(scrobbler, player, api, ui) {
     // Download Quality setting
     const downloadQualitySetting = document.getElementById('download-quality-setting');
     if (downloadQualitySetting) {
+        // Assign categories to the static (native) options already in the HTML
+        const staticCategories = {
+            HI_RES_LOSSLESS: 'Lossless',
+            LOSSLESS: 'Lossless',
+            HIGH: 'AAC',
+            LOW: 'AAC',
+        };
+
+        // Collect static options first (preserving their original order)
+        const allOptions = Array.from(downloadQualitySetting.options).map((opt) => ({
+            value: opt.value,
+            text: opt.textContent,
+            category: staticCategories[opt.value] || 'Other',
+        }));
+
+        // Append custom (ffmpeg-transcoded) format options
+        for (const fmt of customFormats) {
+            allOptions.push({ value: fmt.internalName, text: fmt.displayName, category: fmt.category });
+        }
+
+        // Sort by category order first, then by bitrate descending within each category
+        // so higher-quality options always appear before lower-quality ones.
+        // Options without an explicit kbps value (lossless) use Infinity so they
+        // sort to the top; ties fall back to display-name descending.
+        const getBitrate = (text) => {
+            const m = text.match(/(\d+)\s*kbps/i);
+            return m ? parseInt(m[1], 10) : Infinity;
+        };
+        const categoryOrder = ['Lossless', 'AAC', 'MP3', 'OGG'];
+        allOptions.sort((a, b) => {
+            const ai = categoryOrder.indexOf(a.category);
+            const bi = categoryOrder.indexOf(b.category);
+            const categoryDiff = (ai === -1 ? categoryOrder.length : ai) - (bi === -1 ? categoryOrder.length : bi);
+            if (categoryDiff !== 0) return categoryDiff;
+            const bitrateA = getBitrate(a.text);
+            const bitrateB = getBitrate(b.text);
+            if (bitrateA !== bitrateB) return bitrateB - bitrateA;
+            return b.text.localeCompare(a.text);
+        });
+
+        // Rebuild the select with optgroup elements per category
+        downloadQualitySetting.innerHTML = '';
+        let currentGroup = null;
+        let currentCategory = null;
+        for (const opt of allOptions) {
+            if (opt.category !== currentCategory) {
+                currentCategory = opt.category;
+                currentGroup = document.createElement('optgroup');
+                currentGroup.label = opt.category;
+                downloadQualitySetting.appendChild(currentGroup);
+            }
+            const option = document.createElement('option');
+            option.value = opt.value;
+            option.textContent = opt.text;
+            currentGroup.appendChild(option);
+        }
+
         downloadQualitySetting.value = downloadQualitySettings.getQuality();
 
         downloadQualitySetting.addEventListener('change', (e) => {

js/storage.js

@@ -539,7 +539,13 @@ export const downloadQualitySettings = {
     STORAGE_KEY: 'download-quality',
     getQuality() {
         try {
-            return localStorage.getItem(this.STORAGE_KEY) || 'HI_RES_LOSSLESS';
+            const stored = localStorage.getItem(this.STORAGE_KEY) || 'HI_RES_LOSSLESS';
+            // Migrate legacy value to renamed format
+            if (stored === 'MP3_320') {
+                this.setQuality('FFMPEG_MP3_320');
+                return 'FFMPEG_MP3_320';
+            }
+            return stored;
         } catch {
             return 'HI_RES_LOSSLESS';
         }

js/utils.js

@@ -108,6 +108,17 @@ export const detectAudioFormat = (view, mimeType = '') => {
         return 'flac';
     }
 
+    // Check for OGG signature: "OggS" (0x4F 0x67 0x67 0x53)
+    if (
+        view.byteLength >= 4 &&
+        view.getUint8(0) === 0x4f && // O
+        view.getUint8(1) === 0x67 && // g
+        view.getUint8(2) === 0x67 && // g
+        view.getUint8(3) === 0x53 // S
+    ) {
+        return 'ogg';
+    }
+
     // Check for MP4/M4A signature: "ftyp" at offset 4
     if (
         view.byteLength >= 8 &&
@@ -153,6 +164,7 @@ export const detectAudioFormat = (view, mimeType = '') => {
 
     // Fallback to MIME type
     if (mimeType === 'audio/flac') return 'flac';
+    if (mimeType === 'audio/ogg') return 'ogg';
     if (mimeType === 'audio/mp4' || mimeType === 'audio/x-m4a') return 'mp4';
     if (mimeType === 'audio/mp3' || mimeType === 'audio/mpeg') return 'mp3';
 
@@ -177,8 +189,10 @@ export const getExtensionFromBlob = async (blob) => {
     if (format) return format;
 
     if (blob.type.includes('video')) return 'mp4';
-    if (blob.type === 'audio/mp4' || blob.type === 'audio/x-m4a') return 'm4a';
+    if (mimeType === 'audio/flac') return 'flac';
-    if (blob.type === 'audio/mpeg' || blob.type === 'audio/mp3') return 'mp3';
+    if (mimeType === 'audio/ogg') return 'ogg';
+    if (mimeType === 'audio/mp4' || mimeType === 'audio/x-m4a') return 'mp4';
+    if (mimeType === 'audio/mp3' || mimeType === 'audio/mpeg') return 'mp3';
 
     return 'flac';
 };
@@ -188,8 +202,6 @@ export const getExtensionForQuality = (quality) => {
         case 'LOW':
         case 'HIGH':
             return 'm4a';
-        case 'MP3_320':
-            return 'mp3';
         default:
             return 'flac';
     }