ambient-display 1.1.0

package/.nvmrc

@@ -0,0 +1 @@
+v18.19.0

package/.prettierignore

@@ -0,0 +1,4 @@
+# Package Managers
+package-lock.json
+pnpm-lock.yaml
+yarn.lock

package/.prettierrc

@@ -0,0 +1,17 @@
+{
+	"useTabs": true,
+	"singleQuote": true,
+	"trailingComma": "none",
+	"printWidth": 100,
+	"plugins": [
+		"prettier-plugin-svelte"
+	],
+	"overrides": [
+		{
+			"files": "*.svelte",
+			"options": {
+				"parser": "svelte"
+			}
+		}
+	]
+}

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+## 1.1.0 (2025-03-04)
+
+
+### Features
+
+* added cursor hide ([928c7f8](https://github.com/jthawme/ambient/commit/928c7f8aef867b947d77f198a1bda916ff13167b))
+* added fleshed out adding panel ([0ebbbc2](https://github.com/jthawme/ambient/commit/0ebbbc2189599a94f55ecadcdff18909e1c1dc28))
+* added history system and converted errors ([30977fc](https://github.com/jthawme/ambient/commit/30977fc9444738d7adbd8597656411e2154b9a4f))
+* added screen lock to player ([11f5275](https://github.com/jthawme/ambient/commit/11f52751524d7de83b22ba84887cd330b55b8dda))
+* added sonos fallback plugin ([0acefd8](https://github.com/jthawme/ambient/commit/0acefd8138765705c88c5e0b0c5cc3ad393549b9))
+* introduced events ecosystem and config file injection ([c3ade28](https://github.com/jthawme/ambient/commit/c3ade28661d4709e72f4f1f5505c4564712fe773))
+* removed plugins from root repo ([0b1528e](https://github.com/jthawme/ambient/commit/0b1528e2790cd9f70e71505780317ca19b0ae83f))
+* sewn up the loop of built and running flows ([7b3f21a](https://github.com/jthawme/ambient/commit/7b3f21acce980d42c0e79d0f1bcea2bb5c410c44))
+* switched to a centralised polling system first, to protect against rate limits ([3f33865](https://github.com/jthawme/ambient/commit/3f33865d6b8f528f7e69d6cffd54161f6c5c5d29))
+* updated eco system ([de42b2b](https://github.com/jthawme/ambient/commit/de42b2b5d6341bac2c987c3d48cfdbd0cc8d3791))
+
+
+### Bug Fixes
+
+* added attempt at memoization for rate limiting ([9530833](https://github.com/jthawme/ambient/commit/95308335f7eb740de69ef78c542e821a5823f87e))
+* added run script as seperate ([46d90ed](https://github.com/jthawme/ambient/commit/46d90edac3fafb18e8dc4be1c985bf13ad34baa2))
+* backed off on certain endpoints ([d95b69c](https://github.com/jthawme/ambient/commit/d95b69c8466ce12cdae871bec2911009b7258383))
+* built in messaging to spotify errors ([0cc61cb](https://github.com/jthawme/ambient/commit/0cc61cb5be2b902df259eb11d6012e60e4a7307c))
+* continued to make the project less reliant on local install ([22060cc](https://github.com/jthawme/ambient/commit/22060cc4f3d84ebe7c47e328182b617cf7c7ea68))
+* fixed issue with persisting sdk ([0f7fc23](https://github.com/jthawme/ambient/commit/0f7fc2309ec9a9c790060687af562cd2c5293eb2))
+* fixed reauth strategy class ([cfa328d](https://github.com/jthawme/ambient/commit/cfa328dc1599c397ff85b2319800dce7d628283b))
+* is main check fix ([77d087d](https://github.com/jthawme/ambient/commit/77d087d4dc68428e875d01c0b0259ecd47b2d681))
+* protect the polling async function ([e5282b6](https://github.com/jthawme/ambient/commit/e5282b60050fc217e6d4861988cc603fbd594696))
+* reintroduced package lock for npm ci ([fb906cc](https://github.com/jthawme/ambient/commit/fb906cccb8fd7c6856e1f2af28bd7cc429f8d236))
+* small fixes ([0fc9688](https://github.com/jthawme/ambient/commit/0fc9688dc24629b47aaf96f27087011032fdaa6c))

package/README.md

@@ -0,0 +1,84 @@
+# Ambient
+
+An ambient display screen for spotify, with the configurable ability to also non destructively add songs to the communal queue and control basic playback.
+
+![Screenshot](./screenshot.png?raw=true 'Screenshot of the player')
+
+[Watch a userful video here](https://www.youtube.com/watch?v=0QEBUVzqkY0)
+
+## Like a Spotify Jam?
+
+Yeah pretty much, in fact much worse. But in _some_ ways better. Gives a more 'there is a Spotify instance running by the host, but if you wanna chuck a couple tunes in, go for it' vibe, rather than full control.
+
+It also protects against the DREADED playlist switch. It then also allows the host to disallow jams, it just turns the tighten up a very little amount.
+
+## Installing and running
+
+### Option 1: Install globally
+
+```
+npm i -g ambient-display // or any package manager of course
+
+SPOTIFY_CLIENT_ID=[ID_HERE] SPOTIFY_CLIENT_SECRET=[SECRET_HERE] ambient
+```
+
+or load a config file from somewhere
+
+```
+CONFIG=~/.ambient/ambient.config.js ambient
+```
+
+This will build the sveltekit project and then run the express server
+
+### Option 2: Install in another project [COMING SOON]
+
+Hopefully
+
+### Option 3: Pull the project locally
+
+```
+npm run build // or any package manager of course
+
+node server/run.js
+```
+
+## Config
+
+You can configure Ambient with an `ambient.config.js` file in the root of the folder. All types can be found in [this folder](/server/types/)
+
+| Key                             | Type         | Description                                                                                       | Default                             |
+| ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| port                            | number       | The port in which the server runs on                                                              | `3000`                              |
+| origin                          | string       | The origin of the server, usually the local ip                                                    | `_Your machine's IP address_`       |
+| protocol                        | string       | http:// or https:// (is there another?!)                                                          | `http://`                           |
+| playerRoute                     | string       | The path that the player is routed on                                                             | `/player`                           |
+| verbose                         | boolean      | Whether the app shouts a lot more in the stdout                                                   | `false`                             |
+| api                             | object       | See below                                                                                         |                                     |
+| api.market                      | string       | The spotify market to use a lot of the functions in                                               | `GB`                                |
+| api.searchQueryLimit            | number       | How many search results of each category to display                                               | `10`                                |
+| api.centralisedPolling          | boolean      | Whether to turn the info call onto the server and communicate via websockets                      | `true`                              |
+| api.centralisedPollingTimer     | number       | The internal timer that calls for the info                                                        | 5000                                |
+| api.canAdd                      | boolean      | Gives users the ability to add to the playback via the dashboard                                  | `true`                              |
+| api.canControl                  | boolean      | Gives users the ability to control the playback                                                   | `true`                              |
+| spotify                         | object       | See below                                                                                         |                                     |
+| spotify.client_id               | string       | The spotify Client ID from your app                                                               | `process.env.SPOTIFY_CLIENT_ID`     |
+| spotify.client_secret           | string       | The spotify Client Secret from your app                                                           | `process.env.SPOTIFY_CLIENT_SECRET` |
+| spotify.routePrefix             | string       | The prefixed sub route that the spotify mounting sits on                                          | `/spotify`                          |
+| spotify.routeToken              | string       | The path that spotify redirects to with the token                                                 | `/token`                            |
+| spotify.authenticatedRedirect   | string       | The route that the app redirects too after a successful auth with spotify                         | `/`                                 |
+| spotify.accessTokenJsonLocation | string       | The path to save the access token file, for caching                                               | `./server/spotify_auth.json`        |
+| spotify.scope                   | string[]     | Any additional scopes to initiate spotify with                                                    | `[]`                                |
+| plugins                         | PluginItem[] | An array of [plugins](#plugins) to run                                                            | `[]`                                |
+| pluginOptions                   | object       | Refer to any plugin options for what to place here                                                | `{}`                                |
+| suppressErrors                  | string[]     | Any error events to catch and not send to the frontend, because perhaps a plugin will handle them | `[]`                                |
+
+## Plugins
+
+| Name                                                                | Description                                                                           |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [Kiosk Mode](https://github.com/jthawme/ambient-kiosk-mode)         | Opens fullscreen kiosk mode of app after running                                      |
+| [Sonos Fallback](https://github.com/jthawme/ambient-sonos-fallback) | Controls sonos directly, if spotify's api errors while using Sonos as playback device |
+
+## Reasoning
+
+Spotify's API is excellent, but without being approved for the expanded API grant, its limited to really only hobbyist stuff. This means that you can register your own app, and run this locally and have a customised Spotify Jam scenario, because its running through your credentials. Locally served

package/ambient.config.js.template

@@ -0,0 +1,13 @@
+// import * as KioskPlugin from 'ambient-kiosk-mode';
+// import * as SonosFallbackPlugin from 'ambient-sonos-fallback';
+
+/** @type {import('./server/types/options.js').Config} */
+export default {
+	// plugins: [KioskPlugin, SonosFallbackPlugin],
+
+	// A nice way to pass in the credentials
+	// spotify: {
+	// 	client_id: process.env.SPOTIFY_CLIENT_ID,
+	// 	client_secret: process.env.SPOTIFY_CLIENT_SECRET
+	// }
+};

package/env.template

@@ -0,0 +1,2 @@
+SPOTIFY_CLIENT_ID=
+SPOTIFY_CLIENT_SECRET=

package/eslint.config.js

@@ -0,0 +1,24 @@
+import prettier from "eslint-config-prettier";
+import js from '@eslint/js';
+import { includeIgnoreFile } from '@eslint/compat';
+import svelte from 'eslint-plugin-svelte';
+import globals from 'globals';
+import { fileURLToPath } from 'node:url';
+const gitignorePath = fileURLToPath(new URL("./.gitignore", import.meta.url));
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  includeIgnoreFile(gitignorePath),
+  js.configs.recommended,
+  ...svelte.configs["flat/recommended"],
+  prettier,
+  ...svelte.configs['flat/prettier'],
+  {
+    languageOptions: {
+	  globals: {
+	    ...globals.browser,
+	    ...globals.node
+	  }
+	}
+  }
+];

package/jsconfig.json

@@ -0,0 +1,19 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// If you want to overwrite includes/excludes, make sure to copy over the relevant includes/excludes
+	// from the referenced tsconfig.json - TypeScript does not merge them in
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "ambient-display",
+	"version": "1.1.0",
+	"description": "Like a spotify jam but much worse, but also much better. If you need it, you'll love it.",
+	"type": "module",
+	"bin": {
+		"ambient": "./server/run.js"
+	},
+	"scripts": {
+		"dev": "NODE_ENV=development concurrently \"npm:dev:*\"",
+		"dev:frontend": "vite dev",
+		"dev:server": "nodemon --ignore 'server/*.json' server",
+		"build": "vite build",
+		"preview": "vite preview",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch",
+		"format": "prettier --write .",
+		"lint": "prettier --check . && eslint .",
+		"release": "standard-version",
+		"release:publish": "npm run release && npm publish"
+	},
+	"devDependencies": {
+		"@eslint/compat": "^1.2.3",
+		"@poppanator/sveltekit-svg": "^5.0.0",
+		"@sveltejs/adapter-auto": "^3.0.0",
+		"@sveltejs/adapter-node": "^5.2.9",
+		"@sveltejs/kit": "^2.9.0",
+		"@sveltejs/vite-plugin-svelte": "^5.0.0",
+		"concurrently": "^9.1.0",
+		"eslint": "^9.7.0",
+		"eslint-config-prettier": "^9.1.0",
+		"eslint-plugin-svelte": "^2.36.0",
+		"fs-extra": "^11.2.0",
+		"globals": "^15.0.0",
+		"nodemon": "^3.1.7",
+		"prettier": "^3.3.2",
+		"prettier-plugin-svelte": "^3.2.6",
+		"sharp": "^0.33.5",
+		"sharp-ico": "^0.1.5",
+		"standard-version": "^9.5.0",
+		"svelte": "^5.0.0",
+		"svelte-check": "^4.0.0",
+		"svgo": "^3.3.2",
+		"typescript": "^5.0.0",
+		"vite": "^6.0.0"
+	},
+	"dependencies": {
+		"@spotify/web-api-ts-sdk": "^1.2.0",
+		"ambient-kiosk-mode": "^1.0.1",
+		"ambient-sonos-fallback": "^1.0.1",
+		"bunyan": "^1.8.15",
+		"cors": "^2.8.5",
+		"deepmerge": "^4.3.1",
+		"detect-rpi": "^1.5.0",
+		"dotenv": "^16.4.7",
+		"express": "^4.21.1",
+		"node-fetch": "^3.3.2",
+		"node-vibrant": "3.1.6",
+		"normalize.css": "^8.0.1",
+		"qrcode-svg": "^1.1.0",
+		"sass": "^1.82.0",
+		"socket.io": "^4.8.1",
+		"socket.io-client": "^4.8.1",
+		"sonos": "^1.14.1",
+		"svelte-ionicons": "^2.0.1"
+	}
+}

package/server/api/index.js

@@ -0,0 +1,213 @@
+import { SpotifyApi } from '@spotify/web-api-ts-sdk';
+import { Router } from 'express';
+import { Server } from 'socket.io';
+
+import * as Types from '../types/options.js';
+import { events } from '../events.js';
+import { asyncInterval } from '../utils.js';
+import { log } from '../logs.js';
+import { DEFAULT_OPTIONS, EVENT } from '../constants.js';
+import { apiWrapper, isSpotifyUrl, SpotifyUrl, protect } from './utils.js';
+import { SpotifyInteract } from './interact.js';
+
+const cachedInfo = { current: null };
+
+/**
+ *
+ * @param {Server} io
+ * @param {{current: SpotifyApi | null}} sdk
+ * @param {Types.ApiOptions} opts
+ * @param {boolean} verbose
+ */
+const run = (io, sdk, opts = {}, verbose = false) => {
+	const options = {
+		...DEFAULT_OPTIONS.api,
+		...opts
+	};
+
+	const app = Router();
+
+	app.get(
+		'/artist/:id',
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.artist.topTracks(req.sdk, req.params.id);
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/album/:id',
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.album.get(req.sdk, req.params.id);
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/search',
+		apiWrapper(async (req, res) => {
+			// Special case for handling if someone has posted a Spotify URL into the search box
+			if (isSpotifyUrl(req.query.q)) {
+				const { type, id } = SpotifyUrl(req.query.q);
+
+				switch (type) {
+					case 'track': {
+						const response = await SpotifyInteract.track.get(req.sdk, id);
+						return res.json(response);
+					}
+					case 'artist': {
+						const response = await SpotifyInteract.artist.topTracks(req.sdk, id);
+						return res.json(response);
+					}
+					case 'album': {
+						const response = await SpotifyInteract.album.get(req.sdk, id);
+						return res.json(response);
+					}
+				}
+			}
+
+			const response = await SpotifyInteract.search.query(
+				req.sdk,
+				req.query.q,
+				options.market,
+				options.searchQueryLimit
+			);
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/add',
+		protect([options.canAdd]),
+		apiWrapper(async (req, res) => {
+			const { success } = await SpotifyInteract.queue.add(req.sdk, req.query.uri);
+
+			if (!success) {
+				req.comms.error('Song already in queue');
+			} else {
+				req.comms.message(`Added <em>${req.query.name ?? 'a track'}</em>`, 'track');
+			}
+			events.system('add');
+
+			return res.json({ success });
+		})
+	);
+
+	app.get(
+		'/info',
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.info.get(req.sdk, options.market);
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/queue',
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.queue.get(req.sdk);
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/skipForward',
+		protect([options.canControl]),
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.player.forward(req.sdk);
+
+			req.comms.message('Skipped forward');
+			events.system('skippedForward');
+
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/skipBackward',
+		protect([options.canControl]),
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.player.back(req.sdk);
+
+			req.comms.message('Skipped back');
+			events.system('skippedBackward');
+
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/play',
+		protect([options.canControl]),
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.player.play(req.sdk);
+
+			req.comms.message('Pressed play');
+			events.system('play');
+
+			return res.json(response);
+		})
+	);
+
+	app.get(
+		'/pause',
+		protect([options.canControl]),
+		apiWrapper(async (req, res) => {
+			const response = await SpotifyInteract.player.pause(req.sdk);
+
+			req.comms.message('Pressed pause');
+			events.system('pause');
+
+			return res.json(response);
+		})
+	);
+
+	app.get('/health', (req, res) => res.json({ success: true, authenticated: !!req.sdk }));
+
+	if (options.centralisedPolling) {
+		io.on('connect', (socket) => {
+			if (cachedInfo.current) {
+				if (verbose) {
+					console.log('Sending client current cached track');
+				}
+
+				socket.emit('info', cachedInfo.current);
+			}
+		});
+
+		asyncInterval(async () => {
+			try {
+				if (verbose) {
+					console.log('Running centralised polling');
+				}
+
+				if (!sdk.current) {
+					return;
+				}
+
+				// If there are no clients, don't bother using an API call - or just once if there is no cached info
+				if (io.engine.clientsCount > 0 || !cachedInfo.current) {
+					const info = await SpotifyInteract.info.get(sdk.current);
+					io.emit('info', info);
+
+					// Allows us to pass to new sockets immediately
+					cachedInfo.current = info;
+
+					if (verbose) {
+						console.log('Ran centralised polling');
+					}
+				}
+			} catch (e) {
+				events.error(EVENT.APP_ERROR, e);
+				log.error(e);
+
+				if (verbose) {
+					console.log('Error on polling');
+				}
+			}
+		}, options.centralisedPollingTimer);
+	}
+
+	return app;
+};
+
+export default run;