muzical-ui

library0.1.22jsnpmunverified

Muzical UI is a local-first music player built with Next.js, allowing users to scan folders on their machine, build a library, queue tracks, and play audio in the browser. Version 0.1.22 is the current stable release, with active development on GitHub. It supports browsing MusicBrainz and YouTube for discovery and streaming, stores all data locally via IndexedDB and localStorage, and requires Node.js 20+ and a Chromium-based browser for folder scanning. Differentiators include a self-contained standalone production build, resizable layout, and optional API keys for YouTube and Last.fm for enhanced features.

productivity

npm install muzical-ui

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MUZICAL-UI

muzical-ui

productivityjavascriptv0.1.22

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import MuzicalUI from 'muzical-ui'

✗ const MuzicalUI = require('muzical-ui')

Package is ESM-only. No default export exists; the recommended usage is via the CLI or Next.js server integration.

CLI

✓ npx muzical-ui

✗ node bin/muzical-ui.js (requires build)

Run the CLI directly with npx after installation. The bin script starts the standalone Next.js server.

config

✓ import { config } from 'muzical-ui'

✗ import config from 'muzical-ui'

Named export, not default. Used to configure API keys and preferences.

Install, build, and run the production server with default port.

pnpm add muzical-ui pnpm build npx muzical-ui --port 3000 # Open http://localhost:3000

Debug

Known issues

breakingRequires Node.js 20+

fix

Update Node.js to version 20 or later.

affects: >=0.1.0

breakingChromium-based browser required for folder scanning due to File System Access API

fix

Use Chrome, Edge, or Opera. Firefox and Safari are not supported for local library scanning.

affects: >=0.1.0

deprecatedPrevious bin script path changed in v0.1.20

fix

Use 'npx muzical-ui' or update your scripts to reference 'node bin/muzical-ui.js' after build.

affects: <0.1.20

gotchaLocal storage (IndexedDB/localStorage) is cleared on browser cache wipe; users may lose library data and settings.

fix

Inform users to back up their data or avoid clearing site data.

affects: >=0.1.0

gotchaYouTube and Last.fm API keys stored in localStorage and sent to their respective APIs; keys can be viewed via browser dev tools.

fix

Use restrictive API keys and educate users about local-only storage.

affects: >=0.1.0

Errors

Common errors & fixes

Error: ENOENT: no such file or directory, open '.next/standalone/server.js'

Running CLI without building first.

fix

Run 'pnpm build' before 'npx muzical-ui'.

The File System Access API is not supported on this browser.

Using a non-Chromium browser for local folder scanning.

fix

Switch to a Chromium-based browser (Chrome, Edge, Opera).

YouTube API key is required for reliable video resolution.

Missing YouTube Data API key in Settings.

fix

Obtain an API key from Google Cloud Console and enter it in Settings.

Module not found: Can't resolve 'next'

Next.js not installed as a dependency.

fix

Run 'npm install next' or 'pnpm add next'.

Upgrade

Version history

0.1.22latest on npm

Audit

Dependencies

nextrequiredWeb framework for app routing and server-side rendering

reactrequiredUI library required by Next.js

react-domrequiredDOM rendering required by Next.js

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/f3rnox/muzical-ui ↗

packagemuzical-ui ↗

homepagehttps://github.com/f3rnox/muzical-ui#readme ↗