tidal-ui (lossless-ui)

When developing with or extending lossless-ui, be aware of the following architectural behaviors:

API Proxying

To avoid CORS errors, some requests are proxied through the first-party SvelteKit route at /api/proxy. This allows the browser to communicate with the API directly through the application server.

Caching Rules

The application implements a caching mechanism for safe GET requests. However, certain conditions prevent a response from being cached:

• Headers: Requests containing Authorization, Cookie, or Range headers are not cached.
• Payload Size: Responses larger than the REDIS_CACHE_MAX_BODY_BYTES limit are not cached.
• Content Type: Non-text/JSON payloads are never cached.
• Status Codes: Any 4xx or 5xx status codes are not cached.
• Cache Control: Responses with Cache-Control: no-store or Cache-Control: private are never cached.

The project uses a flat configuration format for ESLint. It integrates recommended rules from JavaScript, TypeScript, and Svelte, while ensuring compatibility with Prettier.

Key configuration details:

• Ignore Files: Uses .gitignore to determine which files to ignore via @eslint/compat.
• Globals: Configures both browser and node environments.
• TypeScript/Svelte Integration: For .svelte, .svelte.ts, and .svelte.js files, it uses typescript-eslint's parser with projectService: true and passes the project's svelte.config.js to the parser options.
• Rule Overrides: The no-undef rule is disabled ('off') to prevent conflicts with TypeScript's own type checking.

import prettier from 'eslint-config-prettier';
import { fileURLToPath } from 'node:url';
import { includeIgnoreFile } from '@eslint/compat';
import js from '@eslint/js';
import svelte from 'eslint-plugin-svelte';
import { defineConfig } from 'eslint/config';
import globals from 'globals';
import ts from 'typescript-eslint';
import svelteConfig from './svelte.config.js';

const gitignorePath = fileURLToPath(new URL('./.gitignore', import.meta.url));

export default defineConfig(
	includeIgnoreFile(gitignorePath),
	js.configs.recommended,
	...ts.configs.recommended,
	...svelte.configs.recommended,
	prettier,
	...svelte.configs.prettier,
	{
		languageOptions: {
			globals: { ...globals.browser, ...globals.node }
		},
		rules: {
			'no-undef': 'off'
		}
	},
	{
		files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
		languageOptions: {
			parserOptions: {
				projectService: true,
				extraFileExtensions: ['.svelte'],
				parser: ts.parser,
				svelteConfig
			}
		}
	}
);

The svelte-prod service uses several environment variables for configuration, primarily for setting the application title and configuring Redis for caching. These variables should be provided in your environment or a .env file used by Docker Compose.

Application Settings

• TITLE: The title of the application.
• NODE_ENV: Set to production by default.
• PORT: The port the application listens on (default 5000).

Redis Configuration

Use these variables to connect to a Redis instance and tune caching behavior:

• REDIS_URL: The full connection URL for Redis.
• REDIS_HOST: The hostname of the Redis server.
• REDIS_PORT: The port of the Redis server.
• REDIS_USERNAME: The username for Redis authentication.
• REDIS_PASSWORD: The password for Redis authentication.
• REDIS_TLS: Whether to use TLS for the Redis connection.

Cache TTL and Limits

• REDIS_CACHE_TTL_SECONDS: General cache Time-To-Live in seconds.
• REDIS_CACHE_TTL_SEARCH_SECONDS: TTL specifically for search results.
• REDIS_CACHE_TTL_TRACK_SECONDS: TTL specifically for tracking data.
• REDIS_CACHE_MAX_BODY_BYTES: Maximum size in bytes for cached bodies.

environment:
  - TITLE=${TITLE}
  - REDIS_URL=${REDIS_URL}
  - REDIS_HOST=${REDIS_HOST}
  - REDIS_PORT=${REDIS_PORT}
  - REDIS_USERNAME=${REDIS_USERNAME}
  - REDIS_PASSWORD=${REDIS_PASSWORD}
  - REDIS_TLS=${REDIS_TLS}
  - REDIS_CACHE_TTL_SECONDS=${REDIS_CACHE_TTL_SECONDS}
  - REDIS_CACHE_TTL_SEARCH_SECONDS=${REDIS_CACHE_TTL_SEARCH_SECONDS}
  - REDIS_CACHE_TTL_TRACK_SECONDS=${REDIS_CACHE_TTL_TRACK_SECONDS}
  - REDIS_CACHE_MAX_BODY_BYTES=${REDIS_CACHE_MAX_BODY_BYTES}

Fetches the audio stream for a track and triggers a browser download for the specified filename.

Parameters:

• trackId: The numeric ID of the track.
• quality: The desired AudioQuality (defaults to 'LOSSLESS').
• filename: The name to be used for the downloaded file.
• options (optional): DownloadTrackOptions to configure behavior like metadata embedding or separate cover downloads.

Key features:

• Metadata Embedding: If configured, uses FFmpeg WASM to embed title, artist, album, track number, disc number, release year, ISRC, and ReplayGain into the file.
• Format Conversion: Can convert AAC/M4A files to MP3 if convertAacToMp3 is set in options.
• Progress Tracking: Provides hooks for download and embedding progress via options.onProgress and options.onFfmpegProgress.

async downloadTrack(
	trackId: number,
	quality: AudioQuality = 'LOSSLESS',
	filename: string,
	options?: DownloadTrackOptions
): Promise<void>