Skip to content

REQUIREMENTS.md

Latest commit

 

History

History
55 lines (42 loc) · 3.53 KB

REQUIREMENTS.md

File metadata and controls

55 lines (42 loc) · 3.53 KB

Inspired by https://brianalexander.com/playlist/ (and the older https://brianalexander.com/player/) 1. Project Overview

The goal is to create a custom WordPress plugin and Gutenberg block named "Setlist Player" (slug: setlist-player). This block will allow users to build and display curated video playlists. The primary use case is for musicians who need to slow down tracks for practice, making keyboard-based controls a priority.

2. Editor Experience (Admin View)

All block functionality will be managed from the editor's sidebar. The block's appearance in the main editor canvas will be a simple placeholder.

  • Playlist Management Panel
    • The main playlist controls will reside in a collapsible sidebar panel.
    • The panel's title will dynamically display the number of videos (e.g., "Playlist (8 Videos)").
    • Videos in the list will be reorderable via drag-and-drop.
    • Each list item will concisely display the video's title. Hovering over the item will reveal additional details (like the Video ID) in a tooltip.
  • Video Adder UI
    • Below the playlist, an "Add Video" section will contain a single text input field and an "Add/Search" button.
    • Add by URL/ID: A user can paste a video URL or ID. The video is immediately added to the playlist.
    • Add by Search: A user can type a search query. A list of the top 5 search results will appear below the search bar. Clicking a result adds it to the main playlist.

3. Front-End Experience (Visitor View)

The block will render a clean and functional video player on the live site.

  • Layout
    • A large, prominent video player ("the stage") will be displayed at the top.
    • Below the player, the full playlist will be displayed as a list of thumbnails and titles.
  • Playback Logic
    • On page load, the first video in the playlist is loaded into the player but does not autoplay.
    • Clicking any video in the list will immediately scroll the user up to the player and load and play that video.
  • Custom Controls
    • Speed Control: A <select> dropdown menu will allow playback speed adjustments from 10% to 150% in 10% increments.
    • Keyboard Shortcuts: Keyboard controls are essential for users who may be wearing gloves (e.g., for drumming) or otherwise cannot use a mouse/trackpad.
      • Spacebar: Toggles Play/Pause.
      • r: Restarts the current video.
      • n: Plays the next video.
      • p: Plays the previous video.
      • i: Increases playback speed by one increment (10%).
      • d: Decreases playback speed by one increment (10%).

4. Admin Settings Page (Plugin-wide)

A dedicated settings page is required to handle the Google API key.

  • Location: A new menu item named "Setlist Player" will be created under the main WordPress "Settings" menu.
  • Functionality:
    • The page will have a single input field for the admin to enter their Google Developer API key.
    • API Key Validation: Upon saving, the plugin must perform a live test call to a low-cost YouTube Data API v3 endpoint.
      • If the call is successful, a confirmation message is displayed, and the key is saved.
      • If the call fails (e.g., wrong permissions, invalid key, quota exceeded), an error message must be displayed explaining the issue, and the invalid key will not be saved. This ensures that the video search feature in the block editor will function correctly.