Skip to content

Home

Jump to bottom
Brandon Saldan edited this page Oct 12, 2024 · 1 revision

Welcome to the Nocturne Wiki

This wiki serves as the central knowledge base for Nocturne. Here you'll find detailed information about the app's features, architecture, and development guidelines.

Useful Links

About the App

Nocturne is a web-based application that interfaces with the Spotify API to provide a rich, interactive music listening experience on the Spotify Car Thing. It's built using modern web technologies and offers a range of features for music playback and playlist management.

Key Features

  • Playback Control: Play, pause, skip tracks, and control volume using Car Thing's hardware.
  • Dynamic UI: The interface updates in real-time to reflect the current playback state.
  • Playlist Management: View and modify your Spotify playlists.
  • Artist and Album Exploration: Browse and play top tracks from artists and albums.
  • User Library Integration: Access and manage your liked tracks.

Technical Overview

  • Frontend: Built with React.js and Next.js
  • Styling: Utilizes Tailwind CSS for responsive and customizable UI
  • State Management: Uses React hooks for local state management
  • API Integration: Interfaces with the Spotify Web API
  • Authentication: Implements Spotify's OAuth 2.0 flow for secure user authentication

Core Components

  1. Main App (pages/_app.jsx): The root component that handles global state, routing, and serves as the main entry point for the application.
  2. Home Page (pages/index.jsx): The landing page of the application, containing the main user interface for browsing and playing music.
  3. Now Playing Page (pages/now-playing.jsx): A dedicated page for displaying and controlling the currently playing track.
  4. Dynamic Pages:
  • Album Page (pages/album/[albumId].jsx): Displays details and tracks for a specific album.
  • Artist Page (pages/artist/[artistId].jsx): Shows information and top tracks for a particular artist.
  • Playlist Page (pages/playlist/[playlistId].jsx): Presents the contents of a specific playlist.
  1. API Routes:
  • Token Handler (pages/api/token.js): Manages the initial token acquisition from Spotify.
  • Token Refresh (pages/api/refresh-token.js): Handles refreshing the Spotify access token.
  • Lyrics Fetcher (pages/api/lyrics.jsx): Retrieves lyrics for the currently playing song.
  1. UI Components:
  • Error Alert (components/ErrorAlert.jsx): Displays error messages to the user.
  • Drawer (components/Drawer.jsx): Shows user playlists in a slide-up menu, allowing users to add songs to playlists in the Now Playing page.
  • Settings (components/Settings.jsx): Manages user preferences and app settings.
  • Sidebar (components/Sidebar.jsx): Navigation component displayed on the Home Page.
  1. Services:
  • Album Service (services/albumService.js): Handles album-related API calls and data management.
  • Artist Service (services/artistService.js): Manages artist-related functionality.
  • Playlist Service (services/playlistService.js): Deals with playlist operations.
  • Radio Service (services/radioService.js): Handles Spotify's radio and recommendation features.
  • User Playlist Service (services/userPlaylistService.js): Manages user-specific playlist operations.

Key Concepts

  • Dynamic Routing: Nocturne uses Next.js's dynamic routing capabilities for album ([albumId].jsx), artist ([artistId].jsx), and playlist ([playlistId].jsx) pages.
  • Server-Side API Routes: Utilizes Next.js API routes (/api) to handle server-side operations like token management and lyrics fetching, keeping sensitive operations secure.
  • Modular Service Architecture: The app is organized into separate service modules (album, artist, playlist, radio, user playlist) for better code organization and maintenance.
  • Real-Time Playback Updates: The Now Playing page (now-playing.jsx) and the Home Page (index.jsx) provide real-time updates of the current track, synchronizing the UI with the Spotify playback state.
  • Dynamic Theming: The app's background changes color based on the currently playing album art.
  • Global State Management: The Main App (_app.jsx) manages global state (like user authentication and current playback) that's shared across different pages and components.
  • Error Handling: A comprehensive error handling system with unique error codes (see Error Codes for details).
  • Lyrics Integration: Nocturne goes beyond basic Spotify functionality by incorporating a lyrics feature using a third-party lyrics API.
  • Settings and Customization: The Settings component (Settings.jsx) provides access to user-customizable options, including enabling/disabling song title scrolling and enabling/disabling the option to display song lyrics.

Development Guidelines

  • Follow React and Next.js best practices.
  • Use functional components and hooks.
  • Implement error handling using the defined error codes.
  • Ensure all new features are responsive and accessible.
  • Write clean code.

Contributing

We welcome contributions from all!

For any questions or support, please contact the development team.

Happy coding!

Clone this wiki locally