stretto

Imported from benkaiser/stretto (AGENTS.md). Install upstream with npx skills add benkaiser/stretto. Copyright stays with the author.

IMPORTANT: before you do anything else, run the beans prime command and heed its output. IMPORTANT: Read files in their entirety, do not read portions of files unless the contents are longer than 2000 lines.

AGENTS.md — Stretto Music Player

Project Overview

Stretto is an open-source, web-based music player (v2.0.0, MIT license) that streams music from YouTube, SoundCloud, and Audius. It runs as a Progressive Web App with offline support, cloud sync, and multi-device remote control.

Live: https://next.kaiserapps.com/

Architecture

Monolithic full-stack application — a single Node.js/Express server serves both a REST API and a server-rendered Pug shell, which boots a React 16 SPA. Not a monorepo, not microservices, not GraphQL.

Directory Structure

stretto/
├── index.js                   # Express server entry point
├── controllers/
│   ├── index.js               # All REST API routes (single Express Router)
│   └── socketio.js            # Socket.IO remote control handlers
├── models/
│   ├── data_mapper.js         # Facade wrapping all model operations
│   ├── user.js                # User model (email, hash, salt, version, googleObject)
│   ├── song.js                # Song model (stores ALL songs for a user as one blob)
│   ├── playlist.js            # Playlist model (stores ALL playlists as one blob)
│   ├── artist.js              # Followed artists model
│   └── shared_playlist.js     # Shared playlist model (keyed by UUID)
├── services/
│   ├── google.js              # Google OAuth2 token verification
│   └── itunes.js              # iTunes Search API (artist lookup, song feed, cover art)
├── src/
│   ├── js/
│   │   ├── index.js           # Frontend entry point (Loader class, initializes subsystems)
│   │   ├── serviceworker.js   # Service worker (offline caching, audio storage)
│   │   ├── models/            # Client-side data models (Song, Playlist, DataLayer)
│   │   ├── services/          # Player engine, streaming, auth, sync, integrations
│   │   └── views/             # React components (routes, layout, pages)
│   └── scss/
│       └── main.scss          # All styles (~850 lines)
├── views/                     # Pug server templates (layout, index, redirects)
├── static/
│   ├── assets/                # Icons, manifest.json, fonts (committed)
│   └── js/                    # Webpack output (gitignored)
├── bin/                       # Docker helper scripts (go, build, run, restart)
├── stubs/
│   └── jquery.js              # jQuery stub (returns null, avoids bootstrap-slider dep)
├── webpack.config.js          # Two entry points: main + serviceworker
├── docker-compose.yml         # MongoDB + web services
├── Dockerfile.local           # Node 16 dev container
├── .env.example               # Required env vars template
├── .github/workflows/deploy.yml  # CI/CD → Dokku
└── package.json               # Dependencies and scripts

Backend

Server Entry (index.js)

• Loads .env via dotenv
• Creates Express + HTTP server + Socket.IO
• Middleware: body-parser, cookie-parser, express-session (MongoDB-backed via connect-mongodb-session)
• Proxies /scapi → https://api-v2.soundcloud.com (SoundCloud API proxy)
• Pug view engine, serves static files from /static
• Routes from controllers/index.js, Socket.IO from controllers/socketio.js

Key API Routes (controllers/index.js)

Authentication: Session-based via req.session.loggedIn. A simple loggedIn middleware function guards protected routes.

Socket.IO (controllers/socketio.js)

Enables remote control across devices. Devices join rooms by user email and can emit playpause, previous, next to control playback on all connected devices.

Database Models (models/)

All models use Mongoose. The DataMapper class (data_mapper.js) is a static facade that wraps all model CRUD.

Critical design note: Songs and playlists are stored as entire blobs per user (one document per user, not per song). Every sync operation uploads/downloads the entire library. A version timestamp on the User model provides optimistic concurrency control.

Password hashing uses PBKDF2 with SHA-512 (10,000 iterations, 512-byte key).

Frontend

Initialization (src/js/index.js)

The Loader class initializes subsystems in order:

1. TitleUpdater → updates browser tab title with current song
2. FirstRunExperience → onboarding flow
3. AccountManager → auth state
4. Keyboard → keyboard shortcuts (Space = play/pause, arrows = next/prev)
5. Theme → loads Bootswatch theme from CDN
6. ModelInitialiser → loads songs/playlists from localStorage
7. RootView → mounts React Router into #react div
8. Lyrics → auto-fetches lyrics via AZLyrics
9. ServiceWorkerClient → registers service worker
10. SoundcloudOAuth → SoundCloud auth initialization

Routing (src/js/views/root.jsx)

React Router v4 (BrowserRouter + Switch):

Layout (src/js/views/layout.jsx)

Responsive with a 700px breakpoint:

• Desktop: Fixed left Sidebar (logo, search, navigation, player controls, album art) + content area
• Mobile: MobileHeader (top navbar) + MobileFooter (bottom player controls) + content area
• Global overlays: Bootbox (modals), AlerterContainer (toasts), ContextMenu (right-click menus)

State Management

No Redux or MobX. Uses a custom observer pattern:

• Song and Playlist are static classes holding in-memory arrays
• They expose addOnChangeListener(callback) and change() (notify) methods
• Components subscribe in constructors and call setState({}) to re-render on changes
• Persistence: DataLayer wraps localStorage; SyncManager syncs to server

Player Architecture (Strategy Pattern)

The Player singleton (src/js/services/player.js) orchestrates playback, delegating to stream-specific implementations:

Player (orchestrator)
  ├── HTML5AudioPlayer            → offline cached files
  ├── YoutubeStreamPlayer         → YouTube via redirect endpoint (library songs)
  ├── YoutubeIframePlayer         → YouTube IFrame API (preview/non-library)
  ├── SoundcloudStreamPlayer      → SoundCloud HLS streams
  └── AudiusStreamPlayer          → Audius API streams

All extend AbstractHTML5AudioPlayer which provides a common interface: dispose(), toggle(), setVolume(), getPosition(), setCurrentTime().

Song IDs are prefixed by source: y_ (YouTube), s_ (SoundCloud), a_ (Audius).

Key Frontend Services (src/js/services/)

Service Worker (src/js/serviceworker.js)

Offline-first PWA strategy:

• App shell caching: /, /static/js/main.js, Google API, Font Awesome
• Navigation preload: Returns cached shell for all SPA routes, background-refetches
• Third-party caching: Bootswatch themes, YouTube thumbnails, album art from various CDNs
• Audio offline storage: Separate stretto-cache-audio cache for downloaded songs
• BroadcastChannel API: Receives DOWNLOAD, OFFLINE_RAW_FILE, REMOVE_OFFLINE, EMIT_OFFLINED messages

Styling

• SCSS — single file src/scss/main.scss
• Bootstrap 3 via Bootswatch CDN themes (15 themes, switchable at runtime in Settings)
• react-bootstrap v0.32 for UI components
• Font Awesome 4.7 for icons
• Custom font: WisdomScript (logo)
• Responsive: 700px breakpoint for mobile vs desktop layout

Build & Dev

NPM Scripts

Webpack (webpack.config.js)

• Two entry points: main → src/js/index.js, serviceworker → src/js/serviceworker.js
• Output: static/js/[name].js
• Babel: @babel/preset-env (last 2 Chrome versions), decorators (legacy), JSX, object rest spread
• Loaders: babel-loader, style-loader + css-loader, sass-loader
• jQuery: Aliased to stubs/jquery.js (returns null) to avoid pulling in full jQuery

Docker

bin/go          # docker-compose up -d
bin/build       # docker-compose build
bin/run <cmd>   # docker-compose run --rm web /bin/bash -c "<cmd>"
bin/restart     # stop → build → start
bin/softrestart # stop → start (no rebuild)

docker-compose.yml defines two services: mongo (MongoDB) and web (Node.js app on port 3000).

Environment Variables (.env)

Required variables (see .env.example):

• GOOGLE_CLIENT_ID — Google OAuth client ID
• SPOTIFY_CLIENT_ID — Spotify API client ID
• SOUNDCLOUD_CLIENT_ID — SoundCloud API client ID
• SMTP_PASSWORD — Zoho SMTP password for password reset emails
• YOUTUBE_REDIRECT_ENDPOINT — YouTube stream redirect URL
• SOUNDCLOUD_REDIRECT_ENDPOINT — SoundCloud stream redirect URL

CI/CD (.github/workflows/deploy.yml)

• Trigger: Push to master
• Action: Deploys to Dokku PaaS at ssh://dokku@kaiserapps.com/stretto-next

External Integrations

Testing

There are no tests. No test framework, test files, or test scripts exist in the project.

Key Patterns & Conventions

1. Singletons: Player, AccountManager, SocketManager, SyncManager are all instantiated at module level and exported as instances (export default new ClassName())
2. Observer pattern: Models use addOnChangeListener/change() for reactive updates instead of Redux
3. Per-user blobs: Database stores entire song/playlist collections as single documents per user — not normalized
4. Source-prefixed IDs: Song IDs use y_, s_, a_ prefixes to identify their streaming source
5. JSX in services: Some service files use .jsx extension and contain React elements (e.g., alerter.jsx, sync_manager.jsx)
6. No TypeScript: Entire codebase is plain JavaScript with JSX
7. Class components: All React components are class-based (no hooks)
8. Global imports: Services and models are imported directly and used as global singletons throughout the codebase