@arraypress/waveform-player 1.0.1 → 1.1.1

package/src/js/core.js

@@ -88,6 +88,10 @@ export class WaveformPlayer {
         this.init();
     }
 
+    // ============================================
+    // Initialization
+    // ============================================
+
     /**
      * Initialize the player
      * @private
@@ -95,6 +99,8 @@ export class WaveformPlayer {
     init() {
         this.createDOM();
         this.createAudio();
+        this.initPlaybackSpeed();
+        this.initKeyboardControls();
         this.bindEvents();
         this.setupResizeObserver();
 
@@ -124,49 +130,84 @@ export class WaveformPlayer {
         this.container.innerHTML = '';
         this.container.className = 'waveform-player';
 
+        // Determine button alignment
+        // Determine button alignment
+        let buttonAlign = this.options.buttonAlign;
+        if (buttonAlign === 'auto') {
+            // Auto-align based on waveform style
+            const style = this.options.waveformStyle;
+            if (style === 'bars') {
+                buttonAlign = 'bottom';
+            } else {
+                buttonAlign = 'center';  // blocks, mirror, line, dots, seekbar all center
+            }
+        }
+
         // Create HTML structure
         this.container.innerHTML = `
-      <div class="waveform-player-inner">
-        <div class="waveform-body">
-          <div class="waveform-track">
-            <button class="waveform-btn" aria-label="Play/Pause" style="
-                border-color: ${this.options.buttonColor};
-                color: ${this.options.buttonColor};
-            ">
-              <span class="waveform-icon-play">${this.options.playIcon}</span>
-              <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
-            </button>
-            
-            <div class="waveform-container">
-              <canvas></canvas>
-              <div class="waveform-loading" style="display:none;"></div>
-              <div class="waveform-error" style="display:none;">
-                <span class="waveform-error-text">Unable to load audio</span>
-              </div>
-            </div>
+  <div class="waveform-player-inner">
+    <div class="waveform-body">
+      <div class="waveform-track waveform-align-${buttonAlign}">
+        <button class="waveform-btn" aria-label="Play/Pause" style="
+            border-color: ${this.options.buttonColor};
+            color: ${this.options.buttonColor};
+        ">
+          <span class="waveform-icon-play">${this.options.playIcon}</span>
+          <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
+        </button>
+        
+        <div class="waveform-container">
+          <canvas></canvas>
+          <div class="waveform-markers"></div>
+          <div class="waveform-loading" style="display:none;"></div>
+          <div class="waveform-error" style="display:none;">
+            <span class="waveform-error-text">Unable to load audio</span>
           </div>
-          
-          <div class="waveform-info">
-            <div class="waveform-text">
-              <span class="waveform-title" style="color: ${this.options.textColor};"></span>
-              ${this.options.subtitle ? `<span class="waveform-subtitle" style="color: ${this.options.textSecondaryColor};">${this.options.subtitle}</span>` : ''}
-            </div>
-            <div style="display: flex; align-items: center; gap: 1rem;">
-              ${this.options.showBPM ? `
-                <span class="waveform-bpm" style="color: ${this.options.textSecondaryColor}; display: none;">
-                  <span class="bpm-value">--</span> BPM
-                </span>
-              ` : ''}
-              ${this.options.showTime ? `
-                <span class="waveform-time" style="color: ${this.options.textSecondaryColor};">
-                  <span class="time-current">0:00</span> / <span class="time-total">0:00</span>
-                </span>
-              ` : ''}
+        </div>
+      </div>
+      
+      <div class="waveform-info">
+        ${this.options.artwork ? `
+          <img class="waveform-artwork" src="${this.options.artwork}" alt="Album artwork" style="
+            width: 40px;
+            height: 40px;
+            border-radius: 4px;
+            object-fit: cover;
+            flex-shrink: 0;
+          ">
+        ` : ''}
+        <div class="waveform-text">
+          <span class="waveform-title" style="color: ${this.options.textColor};"></span>
+          ${this.options.subtitle ? `<span class="waveform-subtitle" style="color: ${this.options.textSecondaryColor};">${this.options.subtitle}</span>` : ''}
+        </div>
+        <div style="display: flex; align-items: center; gap: 1rem;">
+          ${this.options.showBPM ? `
+            <span class="waveform-bpm" style="color: ${this.options.textSecondaryColor}; display: none;">
+              <span class="bpm-value">--</span> BPM
+            </span>
+          ` : ''}
+          ${this.options.showPlaybackSpeed ? `
+            <div class="waveform-speed">
+              <button class="speed-btn" aria-label="Playback speed">
+                <span class="speed-value">1x</span>
+              </button>
+              <div class="speed-menu" style="display: none;">
+                ${this.options.playbackRates.map(rate =>
+            `<button class="speed-option" data-rate="${rate}">${rate}x</button>`
+        ).join('')}
+              </div>
             </div>
-          </div>
+          ` : ''}
+          ${this.options.showTime ? `
+            <span class="waveform-time" style="color: ${this.options.textSecondaryColor};">
+              <span class="time-current">0:00</span> / <span class="time-total">0:00</span>
+            </span>
+          ` : ''}
         </div>
       </div>
-    `;
+    </div>
+  </div>
+`;
 
         // Get references
         this.playBtn = this.container.querySelector('.waveform-btn');
@@ -174,12 +215,16 @@ export class WaveformPlayer {
         this.ctx = this.canvas.getContext('2d');
         this.titleEl = this.container.querySelector('.waveform-title');
         this.subtitleEl = this.container.querySelector('.waveform-subtitle');
+        this.artworkEl = this.container.querySelector('.waveform-artwork');
         this.currentTimeEl = this.container.querySelector('.time-current');
         this.totalTimeEl = this.container.querySelector('.time-total');
         this.bpmEl = this.container.querySelector('.waveform-bpm');
         this.bpmValueEl = this.container.querySelector('.bpm-value');
         this.loadingEl = this.container.querySelector('.waveform-loading');
         this.errorEl = this.container.querySelector('.waveform-error');
+        this.markersContainer = this.container.querySelector('.waveform-markers');
+        this.speedBtn = this.container.querySelector('.speed-btn');
+        this.speedMenu = this.container.querySelector('.speed-menu');
 
         // Set canvas size
         this.resizeCanvas();
@@ -191,10 +236,155 @@ export class WaveformPlayer {
      */
     createAudio() {
         this.audio = new Audio();
-        this.audio.preload = 'metadata';
+        this.audio.preload = this.options.preload || 'metadata';
         this.audio.crossOrigin = 'anonymous';
     }
 
+    // ============================================
+    // Feature Initialization
+    // ============================================
+
+    /**
+     * Initialize playback speed controls
+     * @private
+     */
+    initPlaybackSpeed() {
+        // Set initial playback rate if specified
+        if (this.options.playbackRate && this.options.playbackRate !== 1) {
+            this.audio.playbackRate = this.options.playbackRate;
+        }
+
+        // Initialize speed control UI if enabled
+        if (this.options.showPlaybackSpeed) {
+            this.initSpeedControls();
+        }
+    }
+
+    /**
+     * Initialize speed control UI
+     * @private
+     */
+    initSpeedControls() {
+        const speedBtn = this.container.querySelector('.speed-btn');
+        const speedMenu = this.container.querySelector('.speed-menu');
+
+        if (!speedBtn || !speedMenu) return;
+
+        // Toggle menu
+        speedBtn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            speedMenu.style.display = speedMenu.style.display === 'none' ? 'block' : 'none';
+        });
+
+        // Close menu when clicking outside
+        document.addEventListener('click', () => {
+            speedMenu.style.display = 'none';
+        });
+
+        // Handle speed selection
+        speedMenu.addEventListener('click', (e) => {
+            e.stopPropagation();
+            if (e.target.classList.contains('speed-option')) {
+                const rate = parseFloat(e.target.dataset.rate);
+                this.setPlaybackRate(rate);
+                speedMenu.style.display = 'none';
+            }
+        });
+
+        // Set initial UI state
+        this.updateSpeedUI();
+    }
+
+    /**
+     * Initialize keyboard controls
+     * @private
+     */
+    initKeyboardControls() {
+        // Make container focusable but not in tab order by default
+        this.container.setAttribute('tabindex', '-1');
+
+        // Only activate keyboard controls when explicitly focused (clicked)
+        this.container.addEventListener('click', () => {
+            // Remove focus from all other players
+            WaveformPlayer.getAllInstances().forEach(player => {
+                if (player !== this) {
+                    player.container.setAttribute('tabindex', '-1');
+                }
+            });
+            // Make this one focusable
+            this.container.setAttribute('tabindex', '0');
+            this.container.focus();
+        });
+
+        // Keyboard events
+        this.container.addEventListener('keydown', (e) => {
+            if (document.activeElement !== this.container) return;
+
+            const key = e.key;
+            const currentTime = this.audio.currentTime;
+
+            // Handle number keys 0-9 for seeking
+            if (key >= '0' && key <= '9') {
+                e.preventDefault();
+                this.seekToPercent(parseInt(key) / 10);
+                return;
+            }
+
+            // Handle other keys
+            const actions = {
+                ' ': () => this.togglePlay(),
+                'ArrowLeft': () => this.seekTo(Math.max(0, currentTime - 5)),
+                'ArrowRight': () => this.seekTo(Math.min(this.audio.duration, currentTime + 5)),
+                'ArrowUp': () => this.setVolume(Math.min(1, this.audio.volume + 0.1)),
+                'ArrowDown': () => this.setVolume(Math.max(0, this.audio.volume - 0.1)),
+                'm': () => this.audio.muted = !this.audio.muted,
+                'M': () => this.audio.muted = !this.audio.muted
+            };
+
+            if (actions[key]) {
+                e.preventDefault();
+                actions[key]();
+            }
+        });
+    }
+
+    /**
+     * Initialize Media Session API for system media controls
+     * @private
+     */
+    initMediaSession() {
+        if (!('mediaSession' in navigator) || !this.options.enableMediaSession) return;
+
+        // Set metadata
+        navigator.mediaSession.metadata = new MediaMetadata({
+            title: this.options.title || 'Unknown Track',
+            artist: this.options.subtitle || '',
+            album: this.options.album || '',
+            artwork: this.options.artwork ? [
+                {src: this.options.artwork, sizes: '512x512', type: 'image/jpeg'}
+            ] : []
+        });
+
+        // Set up action handlers
+        navigator.mediaSession.setActionHandler('play', () => this.play());
+        navigator.mediaSession.setActionHandler('pause', () => this.pause());
+        navigator.mediaSession.setActionHandler('seekbackward', () => {
+            this.seekTo(Math.max(0, this.audio.currentTime - 10));
+        });
+        navigator.mediaSession.setActionHandler('seekforward', () => {
+            this.seekTo(Math.min(this.audio.duration, this.audio.currentTime + 10));
+        });
+        navigator.mediaSession.setActionHandler('seekto', (details) => {
+            if (details.seekTime !== null) {
+                this.seekTo(details.seekTime);
+            }
+        });
+    }
+
+    // ============================================
+    // Event Binding
+    // ============================================
+
     /**
      * Bind event listeners
      * @private
@@ -235,6 +425,10 @@ export class WaveformPlayer {
         }
     }
 
+    // ============================================
+    // Audio Loading
+    // ============================================
+
     /**
      * Load audio file
      * @param {string} url - Audio URL
@@ -292,6 +486,8 @@ export class WaveformPlayer {
             }
 
             this.drawWaveform();
+            this.renderMarkers();
+            this.initMediaSession();
 
             // Fire callback
             if (this.options.onLoad) {
@@ -305,6 +501,84 @@ export class WaveformPlayer {
         }
     }
 
+    /**
+     * Load a new track
+     * @param {string} url - Audio URL
+     * @param {string} [title] - Track title
+     * @param {string} [subtitle] - Track subtitle
+     * @param {Object} [options] - Additional options
+     * @returns {Promise<void>}
+     */
+    async loadTrack(url, title = null, subtitle = null, options = {}) {
+        // Stop current playback and clear state
+        if (this.isPlaying) {
+            this.pause();
+        }
+
+        // Reset audio element completely
+        this.audio.src = '';
+        this.audio.load();
+
+        // Clear any errors
+        this.hasError = false;
+        if (this.errorEl) {
+            this.errorEl.style.display = 'none';
+        }
+        if (this.canvas) {
+            this.canvas.style.opacity = '1';
+        }
+        if (this.playBtn) {
+            this.playBtn.disabled = false;
+        }
+
+        // Reset state
+        this.progress = 0;
+        this.waveformData = [];
+
+        // Update options (including preload if specified)
+        this.options = mergeOptions(this.options, {
+            url,
+            title: title || this.options.title,
+            subtitle: subtitle || this.options.subtitle,
+            ...options
+        });
+
+        // Apply preload setting if it was changed
+        if (options.preload) {
+            this.audio.preload = options.preload;
+        }
+
+        // Update UI elements
+        if (this.subtitleEl) {
+            if (subtitle) {
+                this.subtitleEl.textContent = subtitle;
+                this.subtitleEl.style.display = '';
+            } else if (subtitle === '') {
+                this.subtitleEl.style.display = 'none';
+            }
+        }
+
+        // Update artwork if provided
+        if (options.artwork && this.artworkEl) {
+            this.artworkEl.src = options.artwork;
+        }
+
+        // Clear markers if new markers provided
+        if (options.markers) {
+            this.options.markers = options.markers;
+        }
+
+        // Load the new track
+        await this.load(url);
+
+        // Auto-play the new track
+        this.play();
+    }
+
+    // ============================================
+    // Visualization
+    // ============================================
+
     /**
      * Set waveform data
      * @private
@@ -354,6 +628,55 @@ export class WaveformPlayer {
         this.drawWaveform();
     }
 
+    /**
+     * Render markers on the waveform
+     * @private
+     */
+    renderMarkers() {
+        if (!this.options.showMarkers || !this.options.markers?.length || !this.markersContainer) return;
+
+        // Clear existing markers
+        this.markersContainer.innerHTML = '';
+
+        // Don't render if audio duration isn't available yet
+        if (!this.audio || !this.audio.duration || this.audio.duration === 0) {
+            return;
+        }
+
+        // Add each marker
+        this.options.markers.forEach((marker, index) => {
+            const position = (marker.time / this.audio.duration) * 100;
+
+            const markerEl = document.createElement('button');
+            markerEl.className = 'waveform-marker';
+            markerEl.style.left = `${position}%`;
+            markerEl.style.backgroundColor = marker.color || 'rgba(255, 255, 255, 0.5)';
+            markerEl.setAttribute('aria-label', marker.label);
+            markerEl.setAttribute('data-time', marker.time);
+
+            // Tooltip
+            const tooltip = document.createElement('span');
+            tooltip.className = 'waveform-marker-tooltip';
+            tooltip.textContent = marker.label;
+            markerEl.appendChild(tooltip);
+
+            // Click to seek
+            markerEl.addEventListener('click', (e) => {
+                e.stopPropagation();
+                this.seekTo(marker.time);
+                if (this.options.playOnSeek && !this.isPlaying) {
+                    this.play();
+                }
+            });
+
+            this.markersContainer.appendChild(markerEl);
+        });
+    }
+
+    // ============================================
+    // Event Handlers
+    // ============================================
+
     /**
      * Handle canvas click
      * @private
@@ -387,6 +710,8 @@ export class WaveformPlayer {
         if (this.totalTimeEl) {
             this.totalTimeEl.textContent = formatTime(this.audio.duration);
         }
+        // Re-render markers when duration is known
+        this.renderMarkers();
     }
 
     /**
@@ -476,6 +801,10 @@ export class WaveformPlayer {
         }
     }
 
+    // ============================================
+    // Progress Updates
+    // ============================================
+
     /**
      * Start smooth update animation
      * @private
@@ -527,6 +856,10 @@ export class WaveformPlayer {
         }
     }
 
+    // ============================================
+    // UI Updates
+    // ============================================
+
     /**
      * Update BPM display
      * @private
@@ -538,6 +871,23 @@ export class WaveformPlayer {
         }
     }
 
+    /**
+     * Update speed UI to reflect current rate
+     * @private
+     */
+    updateSpeedUI() {
+        const speedValue = this.container.querySelector('.speed-value');
+        if (speedValue) {
+            const rate = this.audio.playbackRate;
+            speedValue.textContent = rate === 1 ? '1x' : `${rate}x`;
+        }
+
+        // Update active state in menu
+        this.container.querySelectorAll('.speed-option').forEach(btn => {
+            btn.classList.toggle('active', parseFloat(btn.dataset.rate) === this.audio.playbackRate);
+        });
+    }
+
     // ============================================
     // Public API
     // ============================================
@@ -576,6 +926,17 @@ export class WaveformPlayer {
         }
     }
 
+    /**
+     * Seek to time in seconds
+     * @param {number} seconds - Time in seconds
+     */
+    seekTo(seconds) {
+        if (this.audio && this.audio.duration) {
+            this.audio.currentTime = Math.max(0, Math.min(seconds, this.audio.duration));
+            this.updateProgress();
+        }
+    }
+
     /**
      * Seek to percentage
      * @param {number} percent - Percentage (0-1)
@@ -597,6 +958,20 @@ export class WaveformPlayer {
         }
     }
 
+    /**
+     * Set playback rate
+     * @param {number} rate - Playback rate (0.5 to 2)
+     */
+    setPlaybackRate(rate) {
+        if (!this.audio) return;
+
+        const clampedRate = Math.max(0.5, Math.min(2, rate));
+        this.audio.playbackRate = clampedRate;
+        this.options.playbackRate = clampedRate;
+
+        this.updateSpeedUI();
+    }
+
     /**
      * Destroy player instance
      */
@@ -618,7 +993,7 @@ export class WaveformPlayer {
     }
 
     // ============================================
-    // Static methods
+    // Static Methods
     // ============================================
 
     /**
@@ -676,5 +1051,4 @@ export class WaveformPlayer {
             throw error;
         }
     }
-
 }

package/src/js/themes.js

@@ -37,6 +37,15 @@ export const DEFAULT_OPTIONS = {
     url: '',
     height: 60,
     samples: 200,
+    preload: 'metadata',
+
+    // Playback
+    playbackRate: 1,
+    showPlaybackSpeed: false,
+    playbackRates: [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2], // Available speeds
+
+    // Layout Options
+    buttonAlign: 'auto', // 'auto', 'top', 'center', 'bottom'
 
     // Default waveform style
     waveformStyle: 'mirror',
@@ -63,10 +72,17 @@ export const DEFAULT_OPTIONS = {
     showBPM: false,
     singlePlay: true,
     playOnSeek: true,
+    enableMediaSession: true,
+
+    // Markers
+    markers: [],
+    showMarkers: true,
 
     // Content
     title: null,
     subtitle: null,
+    artwork: null,
+    album: '',
 
     // Icons (SVG)
     playIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M8 5v14l11-7z"/></svg>',

package/src/js/utils.js

@@ -15,11 +15,15 @@ export function parseDataAttributes(element) {
     if (element.dataset.url) options.url = element.dataset.url;
     if (element.dataset.height) options.height = parseInt(element.dataset.height);
     if (element.dataset.samples) options.samples = parseInt(element.dataset.samples);
+    if (element.dataset.preload) {
+        options.preload = element.dataset.preload;
+    }
 
     // Waveform style attributes
     if (element.dataset.waveformStyle) options.waveformStyle = element.dataset.waveformStyle;
     if (element.dataset.barWidth) options.barWidth = parseInt(element.dataset.barWidth);
     if (element.dataset.barSpacing) options.barSpacing = parseInt(element.dataset.barSpacing);
+    if (element.dataset.buttonAlign) options.buttonAlign = element.dataset.buttonAlign;
 
     // Color preset
     if (element.dataset.colorPreset) options.colorPreset = element.dataset.colorPreset;
@@ -46,13 +50,44 @@ export function parseDataAttributes(element) {
     if (element.dataset.singlePlay) options.singlePlay = element.dataset.singlePlay === 'true';
     if (element.dataset.playOnSeek) options.playOnSeek = element.dataset.playOnSeek === 'true';
 
-    // Content
+    // Content and metadata
     if (element.dataset.title) options.title = element.dataset.title;
     if (element.dataset.subtitle) options.subtitle = element.dataset.subtitle;
+    if (element.dataset.album) options.album = element.dataset.album;
+    if (element.dataset.artwork) options.artwork = element.dataset.artwork;
 
     // Waveform data
     if (element.dataset.waveform) options.waveform = element.dataset.waveform;
 
+    // Markers
+    if (element.dataset.markers) {
+        try {
+            options.markers = JSON.parse(element.dataset.markers);
+        } catch (e) {
+            console.warn('Invalid markers JSON:', e);
+        }
+    }
+
+    // Playback controls
+    if (element.dataset.playbackRate) {
+        options.playbackRate = parseFloat(element.dataset.playbackRate);
+    }
+    if (element.dataset.showPlaybackSpeed !== undefined) {
+        options.showPlaybackSpeed = element.dataset.showPlaybackSpeed === 'true';
+    }
+    if (element.dataset.playbackRates) {
+        try {
+            options.playbackRates = JSON.parse(element.dataset.playbackRates);
+        } catch (e) {
+            console.warn('Invalid playbackRates JSON:', e);
+        }
+    }
+
+    // Media Session API
+    if (element.dataset.enableMediaSession !== undefined) {
+        options.enableMediaSession = element.dataset.enableMediaSession === 'true';
+    }
+
     return options;
 }