Overview

Lament is a free web music player. Instead of building a monolithic application, I separated the client and the backend API, managing all the related repositories under the lamentfm GitHub organization. This specific repository contains the user interface, audio playback logic, and API communication.

Features

• Direct audio playback using HLS.js for stream parsing.
• Server-side proxied API requests for secure data fetching.
• Custom SvelteKit middleware for handling maintenance mode and caching.
• Paginated endpoints for browsing tracks, albums, and artists.
• Song request submission and tracking system.
• Light and dark theme modes implemented with Tailwind CSS v4.

Technical Implementation

Lament operates as a proxying frontend client. It connects to the core backend at api.lament.rynds.my.id using server-side fetching, meaning the authentication credentials and other sensitive tokens are never exposed to the browser. The frontend only talks to its own internal /api routes.

Endpoint Interactions

Here is a breakdown of how the client interacts with the backend API to build the core features:

• Tracks: The /tracks endpoints handle the core audio catalog. They are fully paginated using offset and limit parameters, allowing the frontend to load lists efficiently without overwhelming the network.

  

• Albums: The /albums endpoint groups related tracks. It supports pagination for browsing and a /random route which I use to generate dynamic album discovery sections on the homepage.

  

• Artists: Similar to albums, the /artists endpoint delivers detailed artist profiles and their discography. This helps users navigate the library by exploring the creators behind the music.

  

• Search Engine: The /search endpoint accepts a query string and returns a combined JSON payload containing matching artists, albums, and tracks. In the frontend, I parse this payload and group the results into their respective categories, allowing users to quickly jump to a specific track or browse an artist's discography from a single input field.

  

• Song Request System: I built a /requests endpoint so users can ask for missing music to be added to the database. The frontend provides a form where users submit a text query. This sends a POST request to the API, and administrators can update the status (pending, done, or rejected). The client fetches the user's specific requests so they can track the progress.

  

Development

The Lament ecosystem is split into the frontend client and the backend API, utilizing modern stacks for each side:

Frontend Client (Lament)

• Svelte 5 & SvelteKit 2: Provides the core framework, utilizing Svelte's new Runes for reactive state management and SvelteKit for server-side routing.
• Tailwind CSS v4: Used for rapid UI styling without writing custom CSS files.
• Vite: Acts as the build tool and development server.
• HLS.js: An essential library integrated for parsing and playing HTTP Live Streaming (HLS) audio formats smoothly in the browser.
• Lucide Svelte: Delivers clean, consistent SVG icons throughout the interface.

The frontend project structure keeps API logic centralized in src/lib/server/api.ts for secure server-side fetching, while src/lib/api.ts handles client-side caching and state invalidation.

Backend API (Lament API)

The backend lament-api repository powers the actual data logic:

• Hono: A lightweight, ultrafast web framework used for handling the backend endpoints on the edge.
• LibSQL (Turso): Serves as the relational database, connected via @libsql/client. The database uses a highly normalized structure with tables for tracks, albums, artists, categories, and lyrics.
• Cloudflare Workers: The API is deployed directly to the edge using wrangler, providing low-latency responses globally.
• AWS SDK (S3) / Cloudflare R2: Used for object storage to host the actual audio files and cover art.

Highlights

• Secure Proxy Architecture: The SvelteKit server functions as a secure middleman. Client-side requests hit internal /api/* routes, which securely append the necessary API credentials and forward the request to api.lament.rynds.my.id.
• Advanced Caching Strategy: The client implements an in-memory cache with custom TTLs (Time-To-Live) for public endpoints to reduce unnecessary network requests and backend load, alongside Cache-Control headers at the server level.
• Global Maintenance Middleware: A custom SvelteKit hook (hooks.server.ts) checks the API's maintenance status and redirects users to a maintenance page if the backend is down, with bypass flags available for developers.