Refactor components + better seeking/volume drag behaviour

Author: stronk-dev

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stronk-tech/react-librespot-controller",
   "description": "`go-librespot` squeezebox-alike web frontend for small touchscreens",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "files": [

src/components/Album/AlbumCard.js

@@ -1,15 +1,23 @@
+// Component to render a nice album cover.
 import React, { useEffect, useState, useRef } from 'react';
 import PlaceholderAlbum from "./PlaceHolderAlbum";
 import './AlbumCard.css';
 
-// NOTE: should we make the gradient spin faster? Maybe a full revolution over the course of a song?
+const rotationUpdateInterval = 300; // Milliseconds between each gradient rotation update
+const rotationDenominator = 200; // How quickly the gradient rotates - Higher == slower, lower == quicker.
+const colorThreshold = 50; // Granularity for album color retrieval - Higher == more performance, lower == more dynamic range.
+
+// TODO: add more comments, IE for props
+// TODO: should we make the gradient spin faster? Maybe a full revolution over the course of a song?
+// TODO: should we make it look more like a record player?
 const AlbumCard = ({ title, subtitle, image, isStopped }) => {
-  const [loaded, setLoaded] = useState(false);
-  const [gradient, setGradient] = useState('');
-  const canvasRef = useRef();
+  const [loaded, setLoaded] = useState(false); //< Whether the album image is loaded - fades in the image once loaded
+  const [gradient, setGradient] = useState(''); //< Holds the gradient CSS style (excluding rotation)
+  const canvasRef = useRef(); //< Canvas ref used to extract dominant colors from the album image
+  // Set rotation of gradient based on browser time
   const [rotationDegree, setRotationDegree] = useState(() => {
     const currentTime = new Date().getTime();
-    return (currentTime / 200) % 360;
+    return (currentTime / rotationDenominator) % 360;
   });
 
   // Extract dominant colors using Canvas API
@@ -28,7 +36,6 @@ const AlbumCard = ({ title, subtitle, image, isStopped }) => {
     const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
     const pixels = imageData.data;
     const colorCounts = {};
-    const colorThreshold = 50; // Reduce granularity for performance
 
     // Process pixels to count colors
     for (let i = 0; i < pixels.length; i += 4) {
@@ -50,6 +57,7 @@ const AlbumCard = ({ title, subtitle, image, isStopped }) => {
       : `linear-gradient(to right, ${dominantColors[0]}, ${dominantColors[0]})`;
   };
 
+  // Retrieve dominant colors every time the album image updates
   useEffect(() => {
     if (image) {
       const img = new Image();
@@ -70,16 +78,13 @@ const AlbumCard = ({ title, subtitle, image, isStopped }) => {
     }
   }, [image]);
 
-  // Effect to rotate the gradient continuously at a slower pace
+  // On inital render set an interval to rotate the image
   useEffect(() => {
-    const interval = setInterval(() => {
-      const currentTime = new Date().getTime();
-      setRotationDegree((currentTime / 200) % 360);
-    }, 300);
-
+    const interval = setInterval(setRotationDegree, rotationUpdateInterval);
     return () => clearInterval(interval);
   }, []);
 
+  // Fill in the rotation on render
   const rotatingGradient = `${gradient.replace('to right', `${rotationDegree}deg`)}`;
 
   return (

src/components/Album/PlaceHolderAlbum.js

@@ -1,7 +1,8 @@
+// Placeholder image for when the player is stopped or disconnected.
 import React from "react";
 import "./PlaceHolderAlbum.css";
 
-// TODO: we could do something fun here, like a bouncing DVD logo!
+// TODO: we could do something fun here like a bouncing DVD logo.
 const PlaceholderAlbum = () => {
   return (
     <div className="spotify-player-placeholder-album">

src/components/Controls/MediaButtons.js

@@ -1,7 +1,9 @@
+// Media control buttons - play, pause, forward, backward, shuffle
 import React from "react";
 import { FaPlay, FaPause, FaStepForward, FaStepBackward, FaRandom } from "react-icons/fa";
 import './MediaButtons.css';
 
+// TODO: add more comments, IE for props
 const MediaButtons = ({
   isPlaying,
   handlePlayPause,

src/components/Controls/SeekControls.js

@@ -1,7 +1,8 @@
+// Seek controls - displays the current playback position, duration and a draggable input
 import React, { useState, useRef, useEffect } from "react";
 import './SeekControls.css';
 
-const throttleDelay = 600;
+const throttleDelay = 500; //< Min amount of time between API calls
 
 const formatTime = (milliseconds) => {
   const totalSeconds = Math.floor(milliseconds / 1000);
@@ -10,25 +11,30 @@ const formatTime = (milliseconds) => {
   return `${minutes}:${seconds < 10 ? "0" : ""}${seconds}`;
 };
 
+// TODO: add more comments, IE for props
 const SeekControls = ({
   duration,
-  currentPosition,
+  remotePosition,
   handleSeek,
   isStopped,
-  isConnected
+  isConnected,
+  isPlaying
 }) => {
-  const [localPosition, setLocalPosition] = useState(currentPosition);
-  const timeoutRef = useRef(null);
-  const lastCallTimeRef = useRef(0);
+  const [localPosition, setLocalPosition] = useState(remotePosition); //< Local position for responsiveness while throttling outgoing API calls
+  const intervalRef = useRef(null); //< Used to update the remotePosition on a timeout
+  const timeoutRef = useRef(null); //< Used to space out API calls if we're quicker than the rate limit
+  const lastCallTimeRef = useRef(0); //< Last time we sent out an API call to seek
+  const isDraggingRef = useRef(false); //< Tracks whether the user is dragging
 
+  // Throttled seeking - instantly applies changes locally, but prevents spamming the API while dragging
   const onSeekChange = (e) => {
     const value = (e.target.value / 100) * duration;
     setLocalPosition(value);
+    isDraggingRef.current = true;
 
-    // Throttled API call
     const now = Date.now();
     if (now - lastCallTimeRef.current > throttleDelay) {
-      handleSeek(e); // Call the API
+      handleSeek(e);
       lastCallTimeRef.current = now;
     } else {
       // Clear previous timeout if one exists
@@ -42,11 +48,40 @@ const SeekControls = ({
     }
   };
 
+  // Make the final API call when dragging ends
+  const onSeekEnd = (e) => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    handleSeek(e);
+    isDraggingRef.current = false;
+  };
+
+  // Update the local position when the remote position updates - but only if we're not currently seeking
   useEffect(() => {
-    if (!lastCallTimeRef.current || Date.now() - lastCallTimeRef.current > throttleDelay) {
-      setLocalPosition(currentPosition);
+    if (!isDraggingRef.current) {
+      setLocalPosition(remotePosition);
+    }
+  }, [remotePosition]);
+
+  // Emulate playback for as long as we don't receive any updates on the remote position or are seeking
+  useEffect(() => {
+    if (isPlaying && duration) {
+      intervalRef.current = setInterval(() => {
+        // Skip if we are currently seeking
+        if (isDraggingRef.current) {
+          return;
+        }
+        setLocalPosition((prev) => {
+          const nextPosition = prev + 1000;
+          return nextPosition < duration ? nextPosition : duration;
+        });
+      }, 1000);
+    } else {
+      clearInterval(intervalRef.current);
     }
-  }, [currentPosition]);
+    return () => clearInterval(intervalRef.current);
+  }, [isPlaying, duration]);
 
   return (
     <div className="spotify-player-seek-container">
@@ -57,6 +92,8 @@ const SeekControls = ({
         max="100"
         value={(localPosition / duration) * 100}
         onChange={onSeekChange}
+        onMouseUp={onSeekEnd}
+        onTouchEnd={onSeekEnd}
         className="spotify-player-seek-bar"
         disabled={isStopped || !isConnected}
       />

src/components/Controls/VolumeControls.js

@@ -1,29 +1,32 @@
+// Volume controls - displays the current volume and draggable input
 import React, { useState, useRef, useEffect } from "react";
 import { FaVolumeDown, FaVolumeUp } from "react-icons/fa";
 import './VolumeControls.css';
 
-const throttleDelay = 500;
+const throttleDelay = 300; //< Min amount of time between API calls
 
+// TODO: add more comments, IE for props
 const VolumeControls = ({
   handleVolumeChange,
-  volume,
+  remoteVolume,
   maxVolume,
   isStopped,
   isConnected
 }) => {
-  const [localVolume, setLocalVolume] = useState(volume);
-  const timeoutRef = useRef(null);
-  const lastCallTimeRef = useRef(0);
+  const [localVolume, setLocalVolume] = useState(remoteVolume); //< Local volume for responsiveness while throttling outgoing API calls
+  const timeoutRef = useRef(null); //< Used to space out API calls if we're quicker than the rate limit
+  const lastCallTimeRef = useRef(0); //< Last time we sent out an API call to seek
+  const isDraggingRef = useRef(false); //< Tracks whether the user is dragging
 
+  // Throttled volume change - instantly applies changes locally, but prevents spamming the API while dragging
   const onVolumeChange = (e) => {
     const value = (e.target.value / 100) * maxVolume;
     setLocalVolume(value);
+    isDraggingRef.current = true;
 
-    // Throttled API call
     const now = Date.now();
-
     if (now - lastCallTimeRef.current > throttleDelay) {
-      handleVolumeChange(e); // Call the API
+      handleVolumeChange(e);
       lastCallTimeRef.current = now;
     } else {
       // Clear previous timeout if one exists
@@ -37,11 +40,21 @@ const VolumeControls = ({
     }
   };
 
+  // Make the final API call when dragging ends
+  const onDragEnd = (e) => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    handleVolumeChange(e);
+    isDraggingRef.current = false;
+  };
+
+  // Update the local volume when the remote volume updates - but only if we're not currently seeking
   useEffect(() => {
-    if (!lastCallTimeRef.current || Date.now() - lastCallTimeRef.current > throttleDelay) {
-      setLocalVolume(volume);
+    if (!isDraggingRef.current) {
+      setLocalVolume(remoteVolume);
     }
-  }, [volume]);
+  }, [remoteVolume]);
 
   return (
     <div className="spotify-player-volume-control">
@@ -54,6 +67,8 @@ const VolumeControls = ({
         max="100"
         value={(localVolume / maxVolume) * 100}
         onChange={onVolumeChange}
+        onMouseUp={onDragEnd}
+        onTouchEnd={onDragEnd}
         className="spotify-player-volume-slider"
         disabled={isStopped || !isConnected}
       />

src/components/Info/DeviceTitle.css src/components/Info/Header.csssrc/components/Info/DeviceTitle.css renamed to src/components/Info/Header.css

@@ -1,3 +1,4 @@
+// Displays a header with the client device name and an icon depending on device type
 import React from "react";
 import {
   GiCompactDisc,
@@ -11,8 +12,9 @@ import {
 } from "react-icons/gi";
 import { FaTabletAlt, FaCar, FaMusic, FaQuestionCircle, FaChromecast, FaExclamationCircle } from "react-icons/fa";
 import { MdWatch } from "react-icons/md";
-import './DeviceTitle.css';
+import './Header.css';
 
+// Mapping from device type to which Icon we should render
 const deviceIcons = {
   computer: GiLaptop,
   tablet: FaTabletAlt,
@@ -33,10 +35,11 @@ const deviceIcons = {
   home_thing: GiRadioTower,
 };
 
-const DeviceTitle = ({ isConnected, deviceName, isPlaying, deviceType, isStopped }) => {
-  const name = deviceType?.toLowerCase();
-  const Icon = isStopped ? GiNightSleep : deviceIcons[name] || FaQuestionCircle;
-
+// TODO: expand with settings button
+// TODO: expand with playlists/albums/explore button once we can get albums/playlists from the API
+// TODO: add more comments, IE for props
+const Header = ({ isConnected, deviceName, isPlaying, deviceType, isStopped }) => {
+  const Icon = isStopped ? GiNightSleep : deviceIcons[deviceType?.toLowerCase()] || FaQuestionCircle;
   return (
     <div className="spotify-player-device-title">
       {isConnected ? (
@@ -49,4 +52,4 @@ const DeviceTitle = ({ isConnected, deviceName, isPlaying, deviceType, isStopped
   );
 };
 
-export default DeviceTitle;
+export default Header;

src/components/Info/DeviceTitle.js src/components/Info/Header.jssrc/components/Info/DeviceTitle.js renamed to src/components/Info/Header.js

@@ -1,15 +1,34 @@
+// Renders a text box with info - like a table with playback info or an error message.
 import React from "react";
-import './TrackDetails.css';
+import './TextInfo.css';
 
 // TODO: should display the error somewhere at some point
-const TrackDetails = ({ track, formatReleaseDate, isStopped, isConnected, error }) => {
+// TODO: add more comments, IE for props
+const TextInfo = ({ track, isStopped, isConnected, error }) => {
   if (isStopped || !isConnected) {
     return (
       <div className="spotify-player-track-details spotify-player-message">
         {isConnected ? "The device is currently stopped. Please load a playlist or album." : "Not Connected."}
       </div>
     )
   }
+
+  // Tries to format the release date to YYYY-MM-DD
+  const formatReleaseDate = (releaseDate) => {
+    if (!releaseDate || !releaseDate.length){
+      return "Unknown";
+    }
+    // Match the format with optional spaces: "year:YYYY month:MM day:DD"
+    const match = releaseDate.match(/year:\s*(\d+)\s*month:\s*(\d+)\s*day:\s*(\d+)/);
+    if (match) {
+      const year = match[1];
+      const month = match[2].padStart(2, "0"); // Ensure two-digit month
+      const day = match[3].padStart(2, "0");   // Ensure two-digit day
+      return `${year}-${month}-${day}`;
+    }
+    return releaseDate; // Return as-is for invalid formats
+  };
+
   return (
     <div className="spotify-player-track-details">
       <h4>{track?.name || "N/A"}</h4>
@@ -33,4 +52,4 @@ const TrackDetails = ({ track, formatReleaseDate, isStopped, isConnected, error
   )
 }
 
-export default TrackDetails;
+export default TextInfo;