├── .yarnrc.yml
├── src
    ├── util
    │   ├── debug.ts
    │   ├── spotify-player-state.ts
    │   ├── caching.ts
    │   ├── const.ts
    │   ├── spotify-api.ts
    │   ├── diff.ts
    │   ├── spotify-audio-analysis.ts
    │   └── spotify-ws-api.ts
    ├── types
    │   ├── Observer.ts
    │   ├── Cache.ts
    │   ├── internal
    │   │   └── TypedEventEmitter.ts
    │   ├── SpotifyMedia.ts
    │   ├── SpotifyAnalysis.ts
    │   └── SpotifyCluster.ts
    ├── structs
    │   ├── internal
    │   │   └── ObserverWrapper.ts
    │   ├── PlayerStateEvents.ts
    │   ├── PlayerStateObserver.ts
    │   ├── ClusterObserver.ts
    │   ├── PlayerTrackResolver.ts
    │   ├── AudioAnalysisObserver.ts
    │   ├── CoordinatedSpotifySocket.ts
    │   ├── AudioAnalysisEvents.ts
    │   └── SpotifySocket.ts
    ├── index.ts
    └── test.ts
├── package.json
├── .gitignore
├── README.md
├── yarn.lock
├── tsconfig.json
└── LICENSE


/.yarnrc.yml:
--------------------------------------------------------------------------------
1 | nodeLinker: node-modules
2 | 
3 | yarnPath: .yarn/releases/yarn-3.1.1.cjs
4 | 


--------------------------------------------------------------------------------
/src/util/debug.ts:
--------------------------------------------------------------------------------
1 | import createDebug from "debug";
2 | 
3 | export const debug = createDebug("sactivity");


--------------------------------------------------------------------------------
/src/types/Observer.ts:
--------------------------------------------------------------------------------
1 | export interface Observer<T> {
2 |     observe(target: T): void;
3 |     unobserve(target: T): void;
4 |     disconnect(): void;
5 | }


--------------------------------------------------------------------------------
/src/types/Cache.ts:
--------------------------------------------------------------------------------
1 | export interface Cache<T> {
2 |     resolve(ids: string[]): Promise<Record<string, T>>;
3 |     store(objects: Record<string, T>): Promise<void>;
4 | }


--------------------------------------------------------------------------------
/src/types/internal/TypedEventEmitter.ts:
--------------------------------------------------------------------------------
1 | import EventEmitter from "eventemitter3";
2 | import StrictEventEmitter from "strict-event-emitter-types/types/src";
3 | 
4 | export type TypedEventEmitter<T> = {
5 |     new(): StrictEventEmitter<EventEmitter, T>;
6 | };


--------------------------------------------------------------------------------
/src/util/spotify-player-state.ts:
--------------------------------------------------------------------------------
 1 | import { SpotifyPlayerState } from "../types/SpotifyCluster";
 2 | 
 3 | /**
 4 |  * Computes the current position of a player state
 5 |  * @param playerState player state
 6 |  * @returns current position relative to the start of the song, in milliseconds
 7 |  */
 8 | export function playerStatePosition(playerState: SpotifyPlayerState): number {
 9 |     if (playerState.is_paused) return +playerState.position_as_of_timestamp;
10 | 
11 |     return +playerState.position_as_of_timestamp + (Date.now() - +playerState.timestamp);
12 | }
13 | 


--------------------------------------------------------------------------------
/src/util/caching.ts:
--------------------------------------------------------------------------------
 1 | import { Cache } from "../types/Cache";
 2 | 
 3 | export async function tryCached<T>(ids: string[], refresh: (ids: string[]) => Promise<Record<string, T>>, cache?: Cache<T>): Promise<Record<string, T>> {
 4 |     if (!ids.length) return {};
 5 | 
 6 |     const tracks = cache ? await cache.resolve(ids) : {};
 7 |     const missing = cache ? ids.filter(id => !tracks[id]) : ids;
 8 | 
 9 |     const resolved = missing.length ? await refresh(missing) : {};
10 |     if (cache && Object.keys(resolved).length) await cache.store(resolved);
11 | 
12 |     return Object.assign(resolved, tracks);
13 | }


--------------------------------------------------------------------------------
/src/util/const.ts:
--------------------------------------------------------------------------------
 1 | export const USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36";
 2 | export const SPOTIFY_APP_VERSION = "1.1.56.182.ga73ec2f9";
 3 | export const APP_PLATFORM = "WebPlayer";
 4 | 
 5 | export const CORE_HEADERS = {
 6 |     // "app-platform": APP_PLATFORM,
 7 |     referer: "https://open.spotify.com/",
 8 |     "sec-fetch-dest": "empty",
 9 |     "sec-fetch-mode": "cors",
10 |     "sec-fetch-site": "same-origin",
11 |     // "spotify-app-version": SPOTIFY_APP_VERSION,
12 |     "user-agent": USER_AGENT
13 | }
14 | 


--------------------------------------------------------------------------------
/src/structs/internal/ObserverWrapper.ts:
--------------------------------------------------------------------------------
 1 | import { Observer } from "../../types/Observer";
 2 | 
 3 | export class ObserverWrapper<Target> implements Observer<Target> {
 4 |     public constructor(observer: Observer<Target>) {
 5 |         this.#observer = observer;
 6 |     }
 7 | 
 8 |     #observer: Observer<Target>;
 9 |     
10 |     public observe(target: Target) {
11 |         this.#observer.observe(target);
12 |     }
13 | 
14 |     public unobserve(target: Target) {
15 |         this.#observer.unobserve(target);
16 |     }
17 | 
18 |     public disconnect() {
19 |         this.#observer.disconnect();
20 |     }
21 | }


--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
 1 | export * from "./structs/SpotifySocket";
 2 | export * from "./structs/CoordinatedSpotifySocket";
 3 | export * from "./structs/ClusterObserver";
 4 | export * from "./structs/PlayerStateObserver";
 5 | export * from "./structs/PlayerStateEvents";
 6 | export * from "./structs/PlayerTrackResolver";
 7 | export * from "./structs/AudioAnalysisObserver";
 8 | export * from "./structs/AudioAnalysisEvents";
 9 | 
10 | export * from "./util/spotify-audio-analysis";
11 | export * from "./util/spotify-ws-api";
12 | export * from "./util/spotify-api";
13 | export * from "./util/diff";
14 | 
15 | export * from "./types/SpotifyMedia";
16 | export * from "./types/SpotifyCluster";
17 | export * from "./types/Observer";
18 | export * from "./types/SpotifyAnalysis";
19 | export * from "./types/Cache";


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "sactivity",
 3 |   "version": "2.0.0",
 4 |   "description": "Spotify WebSocket Activity API",
 5 |   "main": "dist/index.js",
 6 |   "types": "dist/index.d.ts",
 7 |   "repository": "https://github.com/EricRabil/sactivity.git",
 8 |   "author": "Eric Rabil <ericjrabil@gmail.com>",
 9 |   "license": "MIT",
10 |   "files": [
11 |     "dist/**"
12 |   ],
13 |   "devDependencies": {
14 |     "@types/debug": "^4.1.5",
15 |     "@types/ws": "^7.4.0",
16 |     "dotenv": "^8.2.0",
17 |     "typescript": "^4.2.3"
18 |   },
19 |   "dependencies": {
20 |     "axios": "^0.21.1",
21 |     "debug": "^4.3.1",
22 |     "eventemitter3": "^4.0.7",
23 |     "isomorphic-ws": "^4.0.1",
24 |     "strict-event-emitter-types": "^2.0.0",
25 |     "ws": "^7.4.4"
26 |   },
27 |   "packageManager": "yarn@3.1.1"
28 | }
29 | 


--------------------------------------------------------------------------------
/src/types/SpotifyMedia.ts:
--------------------------------------------------------------------------------
 1 | export interface SpotifyEntity<Type = string> {
 2 |     href: string;
 3 |     external_urls: {
 4 |         spotify: string;
 5 |     };
 6 |     id: string;
 7 |     name: string;
 8 |     type: Type;
 9 |     uri: string;
10 | }
11 | 
12 | export type SpotifyArtist = SpotifyEntity<"artist">;
13 | 
14 | export interface SpotifyImage {
15 |     height: number;
16 |     url: string;
17 |     width: number;
18 | }
19 | 
20 | export interface SpotifyAlbum extends SpotifyEntity<"album"> {
21 |     artists: SpotifyArtist[];
22 |     images: SpotifyImage[];
23 |     release_date: string;
24 |     release_date_precision: string;
25 |     total_tracks: number;
26 | }
27 | 
28 | export interface SpotifyTrack extends SpotifyEntity<"track"> {
29 |     album: SpotifyAlbum;
30 |     artists: SpotifyArtist[];
31 |     disc_number: number;
32 |     duration_ms: number;
33 |     explicit: boolean;
34 |     external_ids: {
35 |         isrc: string;
36 |     };
37 |     is_local: boolean;
38 |     is_playable: boolean;
39 |     popularity: number;
40 |     preview_url: string;
41 |     track_number: number;
42 | }


--------------------------------------------------------------------------------
/src/test.ts:
--------------------------------------------------------------------------------
 1 | import dotenv from "dotenv";
 2 | import { AudioAnalysisEvents, Cache, CoordinatedSpotifySocket, SpotifyAnalysisResult } from ".";
 3 | 
 4 | dotenv.config();
 5 | 
 6 | const cookies = process.env.SPOTIFY_COOKIES as string;
 7 | 
 8 | function mockCache<T>(): Cache<T> {
 9 |     const cache: Map<string, T> = new Map();
10 | 
11 |     return {
12 |         async resolve(ids: string[]): Promise<Record<string, T>> {
13 |             return ids.reduce((acc, id) => cache.has(id) ? Object.assign(acc, {
14 |                 [id]: cache.get(id) as T
15 |             }) : acc, {});
16 |         },
17 |         async store(tracks: Record<string, T>) {
18 |             for (const id in tracks) {
19 |                 cache.set(id, tracks[id]);
20 |             }
21 |         }
22 |     }
23 | }
24 | 
25 | CoordinatedSpotifySocket.create(cookies).then(({ socket, accessToken }) => {
26 |     const analysisCache: Cache<SpotifyAnalysisResult> = mockCache();
27 | 
28 |     const resolver = new AudioAnalysisEvents({
29 |         cache: analysisCache,
30 |         cookie: cookies
31 |     });
32 | 
33 |     resolver.on("tatum", () => console.log("tatum"));
34 | 
35 |     resolver.observe(socket);
36 | });
37 | 


--------------------------------------------------------------------------------
/src/util/spotify-api.ts:
--------------------------------------------------------------------------------
 1 | import axios from "axios";
 2 | import { SpotifyTrack } from "../types/SpotifyMedia";
 3 | import { CORE_HEADERS } from "./const";
 4 | 
 5 | interface TracksResult {
 6 |     tracks: SpotifyTrack[];
 7 | }
 8 | 
 9 | async function _resolveTracks(ids: string[], accessToken: string): Promise<Record<string, SpotifyTrack>> {
10 |     const { data: { tracks } } = await axios.get<TracksResult>(`https://api.spotify.com/v1/tracks?ids=${ids.join("\n")}&market=from_token`, {
11 |         headers: {
12 |             ...CORE_HEADERS,
13 |             origin: "https://open.spotify.com",
14 |             authorization: `Bearer ${accessToken}`
15 |         }
16 |     });
17 | 
18 |     return tracks.reduce((acc, track) => Object.assign(acc, { [track.id]: track }), {});
19 | }
20 | 
21 | export async function resolveTracks(ids: string[], accessToken: string, regenerate?: () => Promise<string>): Promise<Record<string, SpotifyTrack>> {
22 |     if (ids.length === 0) return {};
23 | 
24 |     try {
25 |         return await _resolveTracks(ids, accessToken);
26 |     } catch (e) {
27 |         if (regenerate && axios.isAxiosError(e) && [401, 403].includes(e.response?.status || 0)) {
28 |             return await _resolveTracks(ids, await regenerate());
29 |         }
30 |         throw e;
31 |     }
32 | }
33 | 


--------------------------------------------------------------------------------
/src/util/diff.ts:
--------------------------------------------------------------------------------
 1 | export type Diffed<T> = T extends object ? {
 2 |     [K in keyof T]: T[K] extends object ? Diffed<T[K]> : {
 3 |         old: T[K];
 4 |         new: T[K];
 5 |     };
 6 | } : Diff<T>;
 7 | 
 8 | export interface Diff<T> {
 9 |     old: T | typeof None;
10 |     new: T;
11 | };
12 | 
13 | export const None = Symbol("None");
14 | 
15 | function isObject(object: unknown): object is object {
16 |     return typeof object === "object" && object !== null;
17 | }
18 | 
19 | export function isDifferent<T>(diff: Diff<T>): boolean {
20 |     if (diff.old === None) return true;
21 |     else return diff.old !== diff.new;
22 | }
23 | 
24 | export function diff<T extends object>(oldObject: T | null, newObject: T): Diffed<T> {
25 |     const diffed: Partial<Diffed<T>> = {};
26 | 
27 |     for (const key in newObject) {
28 |         const value = newObject[key];
29 |         const oldValue = (typeof oldObject === "object" && oldObject !== null) ? oldObject[key] : None;
30 | 
31 |         if (isObject(value)) {
32 |             (diffed as unknown as Record<string, unknown>)[key] = diff(isObject(oldValue) ? oldValue : null, value) as Diffed<T[typeof key]>;
33 |         } else {
34 |             (diffed as unknown as Record<string, unknown>)[key] = {
35 |                 old: oldValue,
36 |                 new: value
37 |             };
38 |         }
39 |     }
40 | 
41 |     return diffed as Diffed<T>;
42 | }


--------------------------------------------------------------------------------
/src/structs/PlayerStateEvents.ts:
--------------------------------------------------------------------------------
 1 | import EventEmitter from "eventemitter3";
 2 | import { TypedEventEmitter } from "../types/internal/TypedEventEmitter";
 3 | import { Observer } from "../types/Observer";
 4 | import { SpotifyPlayerState } from "../types/SpotifyCluster";
 5 | import { isDifferent } from "../util/diff";
 6 | import { PlayerStateObserver } from "./PlayerStateObserver";
 7 | import { SpotifySocket } from "./SpotifySocket";
 8 | 
 9 | type PlayerStateTrigger = "paused" | "resumed" | "track" | "position" | "duration" | "stopped" | "started";
10 | 
11 | type Events = {
12 |     [K in PlayerStateTrigger]: (state: SpotifyPlayerState) => void;
13 | }
14 | 
15 | /**
16 |  * Emits events when various attributes of a state changes
17 |  */
18 | export class PlayerStateEvents extends (EventEmitter as TypedEventEmitter<Events>) implements Observer<SpotifySocket> {
19 |     public constructor() {
20 |         super();
21 | 
22 |         this.#observer = new PlayerStateObserver(states => {
23 |             for (const [diff, state] of states) {
24 |                 if (isDifferent(diff.is_paused)) this.emit(state.is_paused ? "paused" : "resumed", state);
25 |                 if (isDifferent(diff.track.uri)) this.emit("track", state);
26 |                 if (isDifferent(diff.position_as_of_timestamp)) this.emit("position", state);
27 |                 if (isDifferent(diff.duration)) this.emit("duration", state);
28 |                 if (isDifferent(diff.is_playing)) this.emit(state.is_playing ? "started" : "stopped", state);
29 |             }
30 |         });
31 |     }
32 | 
33 |     #observer: PlayerStateObserver;
34 | 
35 |     public observe(target: SpotifySocket) {
36 |         this.#observer.observe(target);
37 |     }
38 | 
39 |     public unobserve(target: SpotifySocket) {
40 |         this.#observer.unobserve(target);
41 |     }
42 | 
43 |     public disconnect() {
44 |         this.#observer.disconnect();
45 |     }
46 | }


--------------------------------------------------------------------------------
/src/structs/PlayerStateObserver.ts:
--------------------------------------------------------------------------------
 1 | import { SpotifyPlayerState } from "../types/SpotifyCluster";
 2 | import { debug } from "../util/debug";
 3 | import { diff, Diffed } from "../util/diff";
 4 | import { ClusterObserver } from "./ClusterObserver";
 5 | import { ObserverWrapper } from "./internal/ObserverWrapper";
 6 | import { SpotifySocket } from "./SpotifySocket";
 7 | 
 8 | export type DiffedPlayerState = Diffed<SpotifyPlayerState>;
 9 | 
10 | export interface PlayerStateCallback {
11 |     (states: [DiffedPlayerState, SpotifyPlayerState][]): any;
12 | }
13 | 
14 | function isSpotifyPlayerState(object: unknown): object is SpotifyPlayerState {
15 |     if (typeof object !== "object" || object === null) return false;
16 |     for (const key of ["duration", "playback_id", "playback_quality", "timestamp", "track"]) {
17 |         if (!(key in object)) return false;
18 |     }
19 |     return true;
20 | }
21 | 
22 | /**
23 |  * Observes player states, firing a callback with a diffed representation and the updated state
24 |  */
25 | export class PlayerStateObserver extends ObserverWrapper<SpotifySocket> {
26 |     public constructor(callback: PlayerStateCallback) {
27 |         super(new ClusterObserver(clusters => {
28 |             const diffedStates: [DiffedPlayerState, SpotifyPlayerState][] = [];
29 | 
30 |             for (const cluster of clusters) {
31 |                 if (!isSpotifyPlayerState(cluster.player_state)) {
32 |                     // Sometimes only a partial player state is included, e.g. no more tracks are left to play.
33 |                     continue;
34 |                 }
35 | 
36 |                 const sessionID = cluster.player_state.session_id;
37 |                 const oldState = this.#states.get(sessionID) || null;
38 |                 this.#states.set(sessionID, cluster.player_state);
39 | 
40 |                 diffedStates.push([
41 |                     diff(oldState, cluster.player_state),
42 |                     cluster.player_state
43 |                 ]);
44 |             }
45 | 
46 |             if (!diffedStates.length) return;
47 | 
48 |             this.#callback(diffedStates);
49 |         }));
50 | 
51 |         this.#callback = callback;
52 |     }
53 | 
54 |     #callback: PlayerStateCallback;
55 |     #states: Map<string, SpotifyPlayerState> = new Map();
56 | }


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Logs
  2 | logs
  3 | *.log
  4 | npm-debug.log*
  5 | yarn-debug.log*
  6 | yarn-error.log*
  7 | lerna-debug.log*
  8 | 
  9 | .yarn/*
 10 | !.yarn/patches
 11 | !.yarn/plugins
 12 | !.yarn/releases
 13 | !.yarn/sdks
 14 | !.yarn/versions
 15 | 
 16 | # Diagnostic reports (https://nodejs.org/api/report.html)
 17 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 18 | 
 19 | # Runtime data
 20 | pids
 21 | *.pid
 22 | *.seed
 23 | *.pid.lock
 24 | 
 25 | # Directory for instrumented libs generated by jscoverage/JSCover
 26 | lib-cov
 27 | 
 28 | # Coverage directory used by tools like istanbul
 29 | coverage
 30 | *.lcov
 31 | 
 32 | # nyc test coverage
 33 | .nyc_output
 34 | 
 35 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 36 | .grunt
 37 | 
 38 | # Bower dependency directory (https://bower.io/)
 39 | bower_components
 40 | 
 41 | # node-waf configuration
 42 | .lock-wscript
 43 | 
 44 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 45 | build/Release
 46 | 
 47 | # Dependency directories
 48 | node_modules/
 49 | jspm_packages/
 50 | 
 51 | # TypeScript v1 declaration files
 52 | typings/
 53 | 
 54 | # TypeScript cache
 55 | *.tsbuildinfo
 56 | 
 57 | # Optional npm cache directory
 58 | .npm
 59 | 
 60 | # Optional eslint cache
 61 | .eslintcache
 62 | 
 63 | # Microbundle cache
 64 | .rpt2_cache/
 65 | .rts2_cache_cjs/
 66 | .rts2_cache_es/
 67 | .rts2_cache_umd/
 68 | 
 69 | # Optional REPL history
 70 | .node_repl_history
 71 | 
 72 | # Output of 'npm pack'
 73 | *.tgz
 74 | 
 75 | # Yarn Integrity file
 76 | .yarn-integrity
 77 | 
 78 | # dotenv environment variables file
 79 | .env
 80 | .env.test
 81 | 
 82 | # parcel-bundler cache (https://parceljs.org/)
 83 | .cache
 84 | 
 85 | # Next.js build output
 86 | .next
 87 | 
 88 | # Nuxt.js build / generate output
 89 | .nuxt
 90 | dist
 91 | 
 92 | # Gatsby files
 93 | .cache/
 94 | # Comment in the public line in if your project uses Gatsby and *not* Next.js
 95 | # https://nextjs.org/blog/next-9-1#public-directory-support
 96 | # public
 97 | 
 98 | # vuepress build output
 99 | .vuepress/dist
100 | 
101 | # Serverless directories
102 | .serverless/
103 | 
104 | # FuseBox cache
105 | .fusebox/
106 | 
107 | # DynamoDB Local files
108 | .dynamodb/
109 | 
110 | # TernJS port file
111 | .tern-port
112 | 


--------------------------------------------------------------------------------
/src/structs/ClusterObserver.ts:
--------------------------------------------------------------------------------
 1 | import { SpotifyCluster, SpotifyPlayerState } from "../types/SpotifyCluster";
 2 | import { SpotifySocket, SpotifyMessageHandler } from "./SpotifySocket";
 3 | 
 4 | export interface SpotifyClusterUpdatePayload {
 5 |     ack_id: string;
 6 |     cluster: SpotifyCluster;
 7 |     devices_that_changed: string[];
 8 |     update_reason: string;
 9 | }
10 | 
11 | /**
12 |  * Ensures a value has the same top-level shape as a SpotifyClusterUpdatePayload
13 |  * @param object the value to inspect
14 |  * @returns whether the object appears to be a SpotifyClusterUpdatePayload
15 |  */
16 | function isClusterUpdatePayload(object: unknown): object is SpotifyClusterUpdatePayload {
17 |     if (typeof object !== "object" || object === null) return false;
18 |     for (const key of ["cluster", "devices_that_changed", "update_reason"]) {
19 |         if (!(key in object)) return false;
20 |     }
21 | 
22 |     return true;
23 | }
24 | 
25 | export interface ClusterCallback {
26 |     (clusters: SpotifyCluster[]): any;
27 | }
28 | 
29 | /**
30 |  * Observes the cluster state on one or more SpotifySockets
31 |  */
32 | export class ClusterObserver {
33 |     public constructor(callback: ClusterCallback) {
34 |         this.#callback = callback;
35 |     }
36 | 
37 |     /**
38 |      * The callback function for this observer
39 |      */
40 |     #callback: ClusterCallback;
41 | 
42 |     /**
43 |      * A set of observed sockets, used when disconnecting
44 |      */
45 |     #observed: Set<SpotifySocket> = new Set();
46 | 
47 |     /**
48 |      * Memoized handler for connect-state messages, so that it can be unregistered
49 |      * @param message the connect-state message
50 |      */
51 |     #connectStateHandler: SpotifyMessageHandler = ({ path, payloads }) => {
52 |         switch (path) {
53 |             case "/v1/cluster":
54 |                 const clusters = payloads.filter(isClusterUpdatePayload).map(update => update.cluster);
55 |                 if (!clusters.length) break;
56 |                 this.#callback(clusters);
57 |         }
58 |     };
59 | 
60 |     /**
61 |      * Observes a SpotifySocket's connect-state API for cluster updates
62 |      * @param target target to observe
63 |      */
64 |     public observe(target: SpotifySocket): void {
65 |         target.registerHandler("connect-state", this.#connectStateHandler);
66 |         this.#observed.add(target);
67 |     }
68 | 
69 |     /**
70 |      * Unobserve's a SpotifySocket's connect-state API
71 |      * @param target target to unobserve
72 |      */
73 |     public unobserve(target: SpotifySocket): void {
74 |         target.unregisterHandler("connect-state", this.#connectStateHandler);
75 |         this.#observed.delete(target);
76 |     }
77 | 
78 |     /**
79 |      * Unobserve's from all SpotifySockets
80 |      */
81 |     public disconnect(): void {
82 |         this.#observed.forEach(target => this.unobserve(target));
83 |     }
84 | }


--------------------------------------------------------------------------------
/src/types/SpotifyAnalysis.ts:
--------------------------------------------------------------------------------
 1 | import { SpotifyTrack } from "./SpotifyMedia";
 2 | 
 3 | export interface SpotifyAnalysisTimeInterval {
 4 |   start: number;
 5 |   duration: number;
 6 |   confidence: number;
 7 | }
 8 | 
 9 | export interface AsyncSpotifyAnalysisCache {
10 |   resolve(id: string): Promise<SpotifyAnalysisResult | undefined | null | void>;
11 |   resolveMetadata(id: string): Promise<SpotifyTrack | undefined | null | void>;
12 |   resolveMany(id: string[]): Promise<Record<string, SpotifyAnalysisResult>>;
13 |   resolveManyMetadatas(id: string[]): Promise<Record<string, SpotifyTrack>>;
14 |   store(id: string, result: SpotifyAnalysisResult): Promise<void>;
15 |   storeMetadata(id: string, result: SpotifyTrack): Promise<void>;
16 |   storeManyMetadatas(metadatas: Record<string, SpotifyTrack>): Promise<void>;
17 | }
18 | 
19 | export namespace SpotifyAnalysisTimeInterval {
20 |   export function isInterval(obj: unknown): obj is SpotifyAnalysisTimeInterval {
21 |     return typeof obj === "object"
22 |       && obj !== null
23 |       && typeof (obj as Record<string, unknown>).start === "number"
24 |       && typeof (obj as Record<string, unknown>).duration === "number"
25 |       && typeof (obj as Record<string, unknown>).confidence === "number";
26 |   }
27 | }
28 | 
29 | export interface SpotifyAnalysisSection extends SpotifyAnalysisTimeInterval {
30 |   loudness: number;
31 |   tempo: number;
32 |   tempo_confidence: number;
33 |   key: number;
34 |   key_confidence: number;
35 |   mode: number;
36 |   mode_confidence: number;
37 |   time_signature: number;
38 |   time_signature_confidence: number;
39 | }
40 | 
41 | export interface SpotifyAnalysisSegment extends SpotifyAnalysisTimeInterval {
42 |   loudness_start: number;
43 |   loudness_max_time: number;
44 |   loudness_max: number;
45 |   loudness_end: number;
46 |   pitches: number[];
47 |   timbre: number[];
48 | }
49 | 
50 | export interface SpotifyAnalysisTrack {
51 |   duration: number;
52 |   sample_md5: string;
53 |   offset_seconds: number;
54 |   window_seconds: number;
55 |   analysis_sample_rate: number;
56 |   analysis_channels: number;
57 |   end_of_fade_in: number;
58 |   start_of_fade_out: number;
59 |   loudness: number;
60 |   tempo: number;
61 |   tempo_confidence: number;
62 |   time_signature: number;
63 |   time_signature_confidence: number;
64 |   key: number;
65 |   key_confidence: number;
66 |   mode: number;
67 |   mode_confidence: number;
68 |   codestring: string;
69 |   code_version: number;
70 |   echoprintstring: string;
71 |   echoprint_version: number;
72 |   synchstring: string;
73 |   synch_version: number;
74 |   rhyhtmstring: string;
75 |   rhyhtm_version: number;
76 | }
77 | 
78 | export interface SpotifyAnalysisResult {
79 |   bars: SpotifyAnalysisTimeInterval[];
80 |   beats: SpotifyAnalysisTimeInterval[];
81 |   sections: SpotifyAnalysisSection[];
82 |   segments: SpotifyAnalysisSegment[];
83 |   tatums: SpotifyAnalysisTimeInterval[];
84 |   track: SpotifyAnalysisTrack;
85 | }


--------------------------------------------------------------------------------
/src/structs/PlayerTrackResolver.ts:
--------------------------------------------------------------------------------
 1 | import { SpotifyTrack } from "../types/SpotifyMedia";
 2 | import { Observer } from "../types/Observer";
 3 | import { SpotifyPlayerState } from "../types/SpotifyCluster";
 4 | import { isDifferent } from "../util/diff";
 5 | import { resolveTracks } from "../util/spotify-api";
 6 | import { PlayerStateObserver } from "./PlayerStateObserver";
 7 | import { SpotifyAccessTokenRegnerator, SpotifySocket } from "./SpotifySocket";
 8 | import { CoordinatedSpotifySocket } from "./CoordinatedSpotifySocket";
 9 | import { Cache } from "../types/Cache";
10 | import { tryCached } from "../util/caching";
11 | import { ObserverWrapper } from "./internal/ObserverWrapper";
12 | 
13 | export interface PlayerTrackResolverCallback {
14 |     (states: {
15 |         state: SpotifyPlayerState;
16 |         track: SpotifyTrack;
17 |     }[]): any;
18 | }
19 | 
20 | export type SpotifyTrackCache = Cache<SpotifyTrack>;
21 | 
22 | export interface PlayerTrackResolverOptions {
23 |     cache?: SpotifyTrackCache;
24 |     accessTokenRegenerator?: SpotifyAccessTokenRegnerator;
25 |     dontInheritAccessTokenRegnerator?: boolean;
26 |     accessToken: string;
27 | }
28 | 
29 | /**
30 |  * Fires a callback with a fully resolved track whenever the current track has changed
31 |  */
32 | export class PlayerTrackResolver extends ObserverWrapper<SpotifySocket> {
33 |     /**
34 |      * @param callback the callback to fire when a new track plays
35 |      * @param options options for the resolver
36 |      */
37 |     constructor(callback: PlayerTrackResolverCallback, options: PlayerTrackResolverOptions) {
38 |         super(new PlayerStateObserver(async states => {
39 |             const updatedStates = states.map(([ _, newState ]) => newState);
40 | 
41 |             const tracks = await this.tracks(updatedStates.map(state => state.track.uri.slice(14)));
42 | 
43 |             this.#callback(updatedStates.filter(state => tracks[state.track.uri.slice(14)]).map(state => ({
44 |                 state,
45 |                 track: tracks[state.track.uri.slice(14)]
46 |             })));
47 |         }));
48 | 
49 |         this.#callback = callback;
50 |         this.#accessToken = options.accessToken;
51 |         this.cache = options.cache;
52 |         this.#accessTokenRegenerator = options.accessTokenRegenerator;
53 |         this.dontInheritAccessTokenRegnerator = options.dontInheritAccessTokenRegnerator || false;
54 |     }
55 | 
56 |     #accessToken: string;
57 |     #callback: PlayerTrackResolverCallback;
58 |     #accessTokenRegenerator?: SpotifyAccessTokenRegnerator;
59 | 
60 |     public dontInheritAccessTokenRegnerator: boolean;
61 |     public cache: SpotifyTrackCache | undefined;
62 | 
63 |     public observe(socket: SpotifySocket): void {
64 |         super.observe(socket);
65 | 
66 |         if (!this.dontInheritAccessTokenRegnerator && !this.#accessTokenRegenerator && socket instanceof CoordinatedSpotifySocket) {
67 |             this.#accessTokenRegenerator = socket.accessTokenRegenerator;
68 |         }
69 |     }
70 | 
71 |     /**
72 |      * Resolves tracks for the given IDs, deferring to the cache when possible
73 |      * @param ids IDs to resolve
74 |      * @returns 
75 |      */
76 |     public async tracks(ids: string[]): Promise<Record<string, SpotifyTrack>> {
77 |         return tryCached(ids, ids => resolveTracks(ids, this.#accessToken, this.#accessTokenRegenerator), this.cache);
78 |     }
79 | }


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # sactivity
 2 | Spotify WebSocket Activity API Library
 3 | 
 4 | ## How it works
 5 | Sactivity has two exports, **Sactivity** and **SpotifyClient**.
 6 | 
 7 | - **Sactivity** is a class that connects to Spotify for you.
 8 | 1. It takes your Spotify authoirzation and uses it to generate a token for connecting to Spotify.
 9 | 2. Then, it connects to one of multiple Spotify "dealers" that push notifications over a WebSocket.
10 | 3. It passes this socket to **SpotifyClient**, but you can also connect to Spotify on your own and pass it to **SpotifyClient**.
11 | 
12 | - **SpotifyClient** handles everything after connecting to the WebSocket, which can still involve some required REST requests.
13 | 1. Waits to receive an initialization payload from Spotify, which includes a connection ID
14 | 2. Calls `PUT https://api.spotify.com/v1/me/notifications/user?connection_id=${connectionID}` to subscribe to activity on the account associated with the connection ID, and by relation, the authorization you provided.
15 | 3. Calls `POST https://guc-spclient.spotify.com/track-playback/v1/devices` and temporarily registers a **fake** Spotify Web Client that will receive notifications from Spotify.
16 | 4. Calls `PUT https://guc-spclient.spotify.com/connect-state/v1/devices/hobs_${clientID}` and subscribes to media player events.
17 | 5. **SpotifyClient** will now emit various events as the media presence changes.
18 | 
19 | | Event Name | Description                                                                                       | Data Type       |
20 | |------------|---------------------------------------------------------------------------------------------------|-----------------|
21 | | volume     | Emitted whenever the volume has changed                                                           | number          |
22 | | playing    | Emitted whenever music is playing again                                                           | void            |
23 | | stopped    | Emitted whenever music is stopped                                                                 | void            |
24 | | paused     | Emitted whenever music is paused                                                                  | void            |
25 | | resumed    | Emitted whenever music is resumed                                                                 | void            |
26 | | track      | Emitted whenever a new track is playing                                                           | SpotifyTrack    |
27 | | options    | Emitted whenever playback options have changed (shuffle, repeat, repeat-one)                      | PlaybackOptions |
28 | | position   | Emitted whenever the position in a song has changed. This includes at the start of a new track.   | string          |
29 | | device     | Emitted whenever the device that is playing music has changed.                                    | SpotifyDevice   |
30 | | close      | Emitted whenever the WebSocket has closed. This is a cue to reconnect after a set amount of time. | void            |
31 | 
32 | In the [tests folder](https://github.com/EricRabil/sactivity/blob/master/test/index.js), you can find a working example.
33 | 
34 | Data types are declared [here](https://github.com/EricRabil/sactivity/blob/master/ts/SpotifyClient.ts)
35 | 
36 | ## Before starting
37 | Sactivity works off of cookies issued by Spotify upon login, which seem to persist for quite a while. Here's how to obtain the cookies needed:
38 | 1. Open Chrome
39 | 2. Open devtools
40 | 3. Go to the network inspector, and in the filter type "get_access_token"
41 | 4. Navigate to https://open.spotify.com in that tab
42 | 5. Click on the network request that shows up, then copy the entirety of the `cookie` header in the Request headers.
43 | 


--------------------------------------------------------------------------------
/src/structs/AudioAnalysisObserver.ts:
--------------------------------------------------------------------------------
 1 | import { SpotifyPlayerState } from "../types/SpotifyCluster";
 2 | import { PlayerStateObserver } from "./PlayerStateObserver";
 3 | import { SpotifySocket } from "./SpotifySocket";
 4 | import { ObserverWrapper } from "./internal/ObserverWrapper";
 5 | import { isDifferent } from "../util/diff";
 6 | import { Cache } from "../types/Cache";
 7 | import { analyzeTracks, createAnalysisToken } from "../util/spotify-audio-analysis";
 8 | import { SpotifyAnalysisResult } from "../types/SpotifyAnalysis";
 9 | import { tryCached } from "../util/caching";
10 | import { debug } from "../util/debug";
11 | 
12 | export interface AudioAnalysisCallback {
13 |     (states: [SpotifyAnalysisResult, SpotifyPlayerState][]): any;
14 | }
15 | 
16 | export type SpotifyAudioAnalysisCache = Cache<SpotifyAnalysisResult>;
17 | 
18 | export interface AudioAnalysisObserverOptions {
19 |     cache?: SpotifyAudioAnalysisCache;
20 |     cookie: string;
21 | }
22 | 
23 | /**
24 |  * Observes the current track, and fires a callback whenever the track changes.
25 |  * 
26 |  * The callback includes the Spotify audio analysis result, and the updated state.
27 |  */
28 | export class AudioAnalysisObserver extends ObserverWrapper<SpotifySocket> {
29 |     public constructor(callback: AudioAnalysisCallback, options: AudioAnalysisObserverOptions) {
30 |         super(new PlayerStateObserver(async states => {
31 |             const changedStates = states.filter(state => isDifferent(state[0].track.uri) || isDifferent(state[0].position_as_of_timestamp) || isDifferent(state[0].is_playing) || isDifferent(state[0].is_paused)).map(state => state[1]);
32 | 
33 |             if (!changedStates.length) return;
34 | 
35 |             const analyzed = await this.analyzeTracks(changedStates.map(state => state.track.uri.slice(14)));
36 | 
37 |             const updates: [SpotifyAnalysisResult, SpotifyPlayerState][] = [];
38 | 
39 |             for (const state of changedStates) {
40 |                 updates.push([analyzed[state.track.uri.slice(14)], state]);
41 |             }
42 | 
43 |             this.#callback(updates);
44 | 
45 |             await this.analyzeTracks(changedStates.filter(state => state.next_tracks).flatMap(state => state.next_tracks.filter(track => !track.uri.includes("delimiter")).map(track => track.uri.slice(14))).slice(0, 5));
46 |         }));
47 | 
48 |         this.#callback = callback;
49 |         this.#cookie = options.cookie;
50 |         this.cache = options.cache;
51 |     }
52 | 
53 |     #callback: AudioAnalysisCallback;
54 |     #cookie: string;
55 |     #token: string | null;
56 | 
57 |     public cache: SpotifyAudioAnalysisCache | undefined;
58 | 
59 |     /**
60 |      * Regnerates the token used to analyze tracks
61 |      * @returns promise of the analysis token
62 |      */
63 |     public async regenerateAnalysisToken(): Promise<string> {
64 |         debug("regenerating analysis token");
65 | 
66 |         const token = await createAnalysisToken(this.#cookie);
67 |         if (!token) throw new Error("Failed to regenerate analysis token.");
68 | 
69 |         return this.#token = token;
70 |     }
71 | 
72 |     /**
73 |      * Analyzes an array of track IDs
74 |      * @param ids IDs to analyze
75 |      * @returns promise of record mapping from track ID to analysis result
76 |      */
77 |     public async analyzeTracks(ids: string[]): Promise<Record<string, SpotifyAnalysisResult>> {
78 |         return tryCached(ids, async ids => analyzeTracks(ids, await this.ensureAnalysisToken(), () => this.regenerateAnalysisToken()), this.cache);
79 |     }
80 | 
81 |     /**
82 |      * Resolves the analysis token if it does not exist
83 |      * @returns new analysis token
84 |      */
85 |     public async ensureAnalysisToken(): Promise<string> {
86 |         if (this.#token) return this.#token;
87 |         else return this.regenerateAnalysisToken();
88 |     }
89 | }


--------------------------------------------------------------------------------
/src/types/SpotifyCluster.ts:
--------------------------------------------------------------------------------
  1 | export interface SpotifyClusterDevice {
  2 |     can_play: boolean;
  3 |     capabilities: {
  4 |         can_be_player: boolean;
  5 |         command_acks: boolean;
  6 |         gaia_eq_connect_id: boolean;
  7 |         is_controllable: boolean;
  8 |         is_observable: boolean;
  9 |         supported_types: string[];
 10 |         supports_command_request: boolean;
 11 |         supports_external_episodes: boolean;
 12 |         supports_gzip_pushes: boolean;
 13 |         supports_logout: boolean;
 14 |         supports_playlist_v2: boolean;
 15 |         supports_rename: boolean;
 16 |         supports_set_options_command: boolean;
 17 |         supports_transfer_command: boolean;
 18 |         volume_steps: number;
 19 |     };
 20 |     client_id: string;
 21 |     device_id: string;
 22 |     device_software_version: string;
 23 |     device_type: string;
 24 |     metadata_map: Record<string, string>;
 25 |     name: string;
 26 |     public_ip: string;
 27 |     spirc_version: string;
 28 |     volume: number;
 29 | }
 30 | 
 31 | export interface SpotifyPlayerContext {
 32 |     context_description: string;
 33 |     context_owner: string;
 34 |     "filtering.predicate": string;
 35 |     image_url: string;
 36 |     "zelda.context_uri": string;
 37 | }
 38 | 
 39 | export interface SpotifyPlayerIndex {
 40 |     page: number;
 41 |     track: number;
 42 | }
 43 | 
 44 | export interface SpotifyPlayerTrack {
 45 |     metadata: {
 46 |         "actions.skipping_next_past_track": string;
 47 |         "actions.skipping_prev_past_track": string;
 48 |         album_title: string;
 49 |         album_uri: string;
 50 |         artist_uri: string;
 51 |         "collection.artist.is_banned": string;
 52 |         "collection.is_banned": string;
 53 |         context_uri: string;
 54 |         entity_uri: string;
 55 |         image_large_url: string;
 56 |         image_small_url: string;
 57 |         image_url: string;
 58 |         image_xlarge_url: string;
 59 |         interaction_id: string;
 60 |         iteration: string;
 61 |         page_instance_id: string;
 62 |         track_player: string;
 63 |     };
 64 |     provider: string;
 65 |     uid: string;
 66 |     uri: string;
 67 | }
 68 | 
 69 | export interface SpotifyPlayerOptions {
 70 |     repeating_context: boolean;
 71 |     repeating_track: boolean;
 72 |     shuffling_context: boolean;
 73 | }
 74 | 
 75 | export interface SpotifyPlayOrigin {
 76 |     feature_classes: string[];
 77 |     feature_identifier: string;
 78 |     feature_version: string;
 79 |     referrer_identifier: string;
 80 |     view_uri: string;
 81 | }
 82 | 
 83 | export interface SpotifyPlaybackQuality {
 84 |     bitrate_level: string;
 85 | }
 86 | 
 87 | export interface SpotifyPlayerRestrictions {
 88 |     disallow_resuming_reasons: string[];
 89 | }
 90 | 
 91 | export interface SpotifyPlayerStateFragment {
 92 |     context_restrictions: Record<string, unknown>;
 93 |     context_uri: string;
 94 |     context_url: string;
 95 |     is_paused: boolean;
 96 |     is_playing: boolean;
 97 |     is_system_initiated: boolean;
 98 |     next_tracks: SpotifyPlayerTrack[];
 99 |     options: SpotifyPlayerOptions;
100 |     page_metadata: Record<string, unknown>;
101 |     play_origin: SpotifyPlayOrigin;
102 |     playback_speed: number;
103 |     position_as_of_timestamp: string;
104 |     prev_tracks: SpotifyPlayerTrack[];
105 |     queue_revision: string;
106 |     restrictions: SpotifyPlayerRestrictions;
107 |     session_id: string;
108 |     suppressions: Record<string, unknown>;
109 | }
110 | 
111 | export interface SpotifyPlayerState extends SpotifyPlayerStateFragment {
112 |     context_metadata: SpotifyPlayerContext;
113 |     duration: string;
114 |     index: SpotifyPlayerIndex;
115 |     playback_id: string;
116 |     playback_quality: SpotifyPlaybackQuality;
117 |     timestamp: string;
118 |     track: SpotifyPlayerTrack;
119 | }
120 | 
121 | export interface SpotifyCluster {
122 |     active_device_id: string;
123 |     devices: Record<string, SpotifyClusterDevice>;
124 |     need_full_player_state: boolean;
125 |     not_playing_since_timestamp?: string;
126 |     player_state: SpotifyPlayerState | SpotifyPlayerStateFragment;
127 |     server_timestamp_ms: string;
128 |     timestamp: string;
129 |     transfer_data_timestamp: string;
130 | }
131 | 


--------------------------------------------------------------------------------
/src/util/spotify-audio-analysis.ts:
--------------------------------------------------------------------------------
  1 | import axios from "axios";
  2 | import { SpotifyAnalysisResult } from "../types/SpotifyAnalysis";
  3 | import { CORE_HEADERS, USER_AGENT } from "./const";
  4 | 
  5 | const SPOTIFY_ANALYSIS_TOKEN = (clientID: string) => `https://accounts.spotify.com/authorize?response_type=token&redirect_uri=https%3A%2F%2Fdeveloper.spotify.com%2Fcallback&client_id=${clientID}&state=${Math.random().toString(36).substring(7)}`;
  6 | const SPOTIFY_AUDIO_ANALYSIS = (trackID: string) => `https://api.spotify.com/v1/audio-analysis/${trackID}`;
  7 | 
  8 | /**
  9 |  * Generates an audio analysis token from the developer portal. This is highly ephemeral and should be expected to expire very quickly.
 10 |  * @param cookie open.spotify.com cookies
 11 |  * @returns promise of an audio analysis token, or null if it failed
 12 |  */
 13 | export async function createAnalysisToken(cookie: string): Promise <string | null> {
 14 |     const headers = {
 15 |         accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
 16 |         "accept-encoding": "gzip, deflate, br",
 17 |         "accept-language": "en",
 18 |         "cache-control": "max-age=0",
 19 |         cookie,
 20 |         "referer": "https://developer.spotify.com/callback/",
 21 |         "sec-fetch-dest": "document",
 22 |         "sec-fetch-mode": "navigate",
 23 |         "sec-fetch-site": "same-origin",
 24 |         "sec-fetch-user": "?1",
 25 |         "upgrade-insecure-requests": "1",
 26 |         "user-agent": USER_AGENT
 27 |     }
 28 | 
 29 |     const page = await axios.get("https://developer.spotify.com/console/get-audio-analysis-track/", {
 30 |         headers
 31 |     });
 32 | 
 33 |     const bits = /&client_id=(.*)`/g.exec(page.data);
 34 |     if(!bits) return null;
 35 | 
 36 |     const [, clientID] = bits;
 37 | 
 38 |     const result = await axios.get(SPOTIFY_ANALYSIS_TOKEN(clientID), {
 39 |         headers: {
 40 |             ...headers,
 41 |             referer: "https://developer.spotify.com/"
 42 |         },
 43 |         maxRedirects: 0,
 44 |         validateStatus: status => status === 302
 45 |     });
 46 | 
 47 |     const location = result.headers.location;
 48 |     if(!location) return null;
 49 | 
 50 |     const tokenBits = /access_token=(.*)&token_/g.exec(location);
 51 |     if(!tokenBits) return null;
 52 | 
 53 |     return tokenBits[1] || null;
 54 | }
 55 | 
 56 | /**
 57 |  * Analyzes a track
 58 |  * @param id ID of the track to analyze
 59 |  * @param token analysis token
 60 |  * @param regnerateToken callback to regenerate the analysis token
 61 |  * @returns promise of an analyzed track
 62 |  */
 63 | export async function analyzeTrack(id: string, token: string, regnerateToken?: () => Promise<string>): Promise<SpotifyAnalysisResult> {
 64 |     try {
 65 |         const { data } = await axios.get<SpotifyAnalysisResult>(SPOTIFY_AUDIO_ANALYSIS(id), {
 66 |             headers: {
 67 |               authorization: `Bearer ${token}`,
 68 |               ...CORE_HEADERS
 69 |             },
 70 |             responseType: 'json'
 71 |         });
 72 |     
 73 |         return data;
 74 |     } catch (e) {
 75 |         if (!axios.isAxiosError(e) || !e.response || e.response.status !== 401 || e.response.data.error.message !== "The access token expired" || !regnerateToken) throw e;
 76 | 
 77 |         return await analyzeTrack(id, await regnerateToken());
 78 |     }
 79 | }
 80 | 
 81 | /**
 82 |  * Analyzes an array of track IDs, returning a dictionary mapping their ID to the analysis result
 83 |  * @param ids IDs to analyze
 84 |  * @param token analysis token
 85 |  * @param regenerateToken callback to regenerate the analysis token
 86 |  * @returns promise of a dictionary mapping track ID to analysis result
 87 |  */
 88 | export async function analyzeTracks(ids: string[], token: string, regenerateToken?: () => Promise<string>): Promise<Record<string, SpotifyAnalysisResult>> {
 89 |     if (!ids.length) return {};
 90 | 
 91 |     const innerRegenerateToken = regenerateToken ? () => regenerateToken().then(newToken => token = newToken) : undefined;
 92 | 
 93 |     const tracks: Record<string, SpotifyAnalysisResult> = {};
 94 | 
 95 |     for (const id of ids) {
 96 |         tracks[id] = await analyzeTrack(id, token, innerRegenerateToken);
 97 |     }
 98 | 
 99 |     return tracks;
100 | }


--------------------------------------------------------------------------------
/yarn.lock:
--------------------------------------------------------------------------------
  1 | # This file is generated by running "yarn install" inside your project.
  2 | # Manual changes might be lost - proceed with caution!
  3 | 
  4 | __metadata:
  5 |   version: 5
  6 |   cacheKey: 8
  7 | 
  8 | "@types/debug@npm:^4.1.5":
  9 |   version: 4.1.5
 10 |   resolution: "@types/debug@npm:4.1.5"
 11 |   checksum: 36bdb74909be193aeeb8c9bb64ef45d691f35181dcf75285728ec1e07103cb91042be2e8294f0624fc5922d9b4f68482faf5ea3068288577ebdccee76cd7870c
 12 |   languageName: node
 13 |   linkType: hard
 14 | 
 15 | "@types/node@npm:*":
 16 |   version: 14.14.35
 17 |   resolution: "@types/node@npm:14.14.35"
 18 |   checksum: 6d6e428b6c504ede62e63dddf83439d3f10b3b283132172f7c3b1ef49b4f499afcfd2e4601e3019074b2dd140ee109a9b63bbd6a18a089c89e45108fa8d5b1ee
 19 |   languageName: node
 20 |   linkType: hard
 21 | 
 22 | "@types/ws@npm:^7.4.0":
 23 |   version: 7.4.0
 24 |   resolution: "@types/ws@npm:7.4.0"
 25 |   dependencies:
 26 |     "@types/node": "*"
 27 |   checksum: afc0060614ccc9382e0e2900220088bedbbdf9cf828b03990bcca9c9c0167bd2aa8b59cd001419ea804e5cc3b1668cc0c6c4aeb60f63c2a36814bed3f0d20528
 28 |   languageName: node
 29 |   linkType: hard
 30 | 
 31 | "axios@npm:^0.21.1":
 32 |   version: 0.21.1
 33 |   resolution: "axios@npm:0.21.1"
 34 |   dependencies:
 35 |     follow-redirects: ^1.10.0
 36 |   checksum: c87915fa0b18c15c63350112b6b3563a3e2ae524d7707de0a73d2e065e0d30c5d3da8563037bc29d4cc1b7424b5a350cb7274fa52525c6c04a615fe561c6ab11
 37 |   languageName: node
 38 |   linkType: hard
 39 | 
 40 | "debug@npm:^4.3.1":
 41 |   version: 4.3.1
 42 |   resolution: "debug@npm:4.3.1"
 43 |   dependencies:
 44 |     ms: 2.1.2
 45 |   peerDependenciesMeta:
 46 |     supports-color:
 47 |       optional: true
 48 |   checksum: 2c3352e37d5c46b0d203317cd45ea0e26b2c99f2d9dfec8b128e6ceba90dfb65425f5331bf3020fe9929d7da8c16758e737f4f3bfc0fce6b8b3d503bae03298b
 49 |   languageName: node
 50 |   linkType: hard
 51 | 
 52 | "dotenv@npm:^8.2.0":
 53 |   version: 8.2.0
 54 |   resolution: "dotenv@npm:8.2.0"
 55 |   checksum: ad4c8e0df3e24b4811c8e93377d048a10a9b213dcd9f062483b4a2d3168f08f10ec9c618c23f5639060d230ccdb174c08761479e9baa29610aa978e1ee66df76
 56 |   languageName: node
 57 |   linkType: hard
 58 | 
 59 | "eventemitter3@npm:^4.0.7":
 60 |   version: 4.0.7
 61 |   resolution: "eventemitter3@npm:4.0.7"
 62 |   checksum: 1875311c42fcfe9c707b2712c32664a245629b42bb0a5a84439762dd0fd637fc54d078155ea83c2af9e0323c9ac13687e03cfba79b03af9f40c89b4960099374
 63 |   languageName: node
 64 |   linkType: hard
 65 | 
 66 | "follow-redirects@npm:^1.10.0":
 67 |   version: 1.13.3
 68 |   resolution: "follow-redirects@npm:1.13.3"
 69 |   peerDependenciesMeta:
 70 |     debug:
 71 |       optional: true
 72 |   checksum: 4b5aaa91a0f938547a083d001a572da4d6b7586b699f330da8794ae2cf8b0d8628bcde794f9b205fbe6c6dcab30272454e723aed8f5540bf47a41fa8c7e36441
 73 |   languageName: node
 74 |   linkType: hard
 75 | 
 76 | "isomorphic-ws@npm:^4.0.1":
 77 |   version: 4.0.1
 78 |   resolution: "isomorphic-ws@npm:4.0.1"
 79 |   peerDependencies:
 80 |     ws: "*"
 81 |   checksum: d7190eadefdc28bdb93d67b5f0c603385aaf87724fa2974abb382ac1ec9756ed2cfb27065cbe76122879c2d452e2982bc4314317f3d6c737ddda6c047328771a
 82 |   languageName: node
 83 |   linkType: hard
 84 | 
 85 | "ms@npm:2.1.2":
 86 |   version: 2.1.2
 87 |   resolution: "ms@npm:2.1.2"
 88 |   checksum: 673cdb2c3133eb050c745908d8ce632ed2c02d85640e2edb3ace856a2266a813b30c613569bf3354fdf4ea7d1a1494add3bfa95e2713baa27d0c2c71fc44f58f
 89 |   languageName: node
 90 |   linkType: hard
 91 | 
 92 | "sactivity@workspace:.":
 93 |   version: 0.0.0-use.local
 94 |   resolution: "sactivity@workspace:."
 95 |   dependencies:
 96 |     "@types/debug": ^4.1.5
 97 |     "@types/ws": ^7.4.0
 98 |     axios: ^0.21.1
 99 |     debug: ^4.3.1
100 |     dotenv: ^8.2.0
101 |     eventemitter3: ^4.0.7
102 |     isomorphic-ws: ^4.0.1
103 |     strict-event-emitter-types: ^2.0.0
104 |     typescript: ^4.2.3
105 |     ws: ^7.4.4
106 |   languageName: unknown
107 |   linkType: soft
108 | 
109 | "strict-event-emitter-types@npm:^2.0.0":
110 |   version: 2.0.0
111 |   resolution: "strict-event-emitter-types@npm:2.0.0"
112 |   checksum: 91ef62364cad9ece9ab9984e806b1c6d947d0617437a25605fff0cbfae59ac6a8d641257a168c1d5f2909809a467c714f027fdccb70b6155d68eac0dc1535299
113 |   languageName: node
114 |   linkType: hard
115 | 
116 | "typescript@npm:^4.2.3":
117 |   version: 4.2.3
118 |   resolution: "typescript@npm:4.2.3"
119 |   bin:
120 |     tsc: bin/tsc
121 |     tsserver: bin/tsserver
122 |   checksum: b4a2020c021211184ac15caf59936b2089c13e79685f340a31aaa839c9de2f73b44a5e3757292de6cdad2ed967aef80d4592161b814cc29c0570f261850c4bca
123 |   languageName: node
124 |   linkType: hard
125 | 
126 | "typescript@patch:typescript@^4.2.3#~builtin<compat/typescript>":
127 |   version: 4.2.3
128 |   resolution: "typescript@patch:typescript@npm%3A4.2.3#~builtin<compat/typescript>::version=4.2.3&hash=493e53"
129 |   bin:
130 |     tsc: bin/tsc
131 |     tsserver: bin/tsserver
132 |   checksum: f97b1f885444f13c340127a0918b17d0c4e5c248f99203a22712b3b43d7129c9c7b95437e4f1de99edf79d3046fa9e15356fb5d27d9d94e47a98158c8b18fda5
133 |   languageName: node
134 |   linkType: hard
135 | 
136 | "ws@npm:^7.4.4":
137 |   version: 7.4.4
138 |   resolution: "ws@npm:7.4.4"
139 |   peerDependencies:
140 |     bufferutil: ^4.0.1
141 |     utf-8-validate: ^5.0.2
142 |   peerDependenciesMeta:
143 |     bufferutil:
144 |       optional: true
145 |     utf-8-validate:
146 |       optional: true
147 |   checksum: a0dd15af5270652d18e6fe866d393d43d4378f7c883dbbd01789a664abd6b763c5be7151ba987973eca4a93a249afbe4a2b53458cd7200e04bde457b7a3a4e1a
148 |   languageName: node
149 |   linkType: hard
150 | 


--------------------------------------------------------------------------------
/src/structs/CoordinatedSpotifySocket.ts:
--------------------------------------------------------------------------------
  1 | import { SpotifyAccessTokenRegnerator, SpotifySocket } from "./SpotifySocket";
  2 | import WebSocket from "isomorphic-ws";
  3 | import { automatedCreateSpotifyClient, connectState, getAccessToken, sendCommand, SpotifyDevice, trackPlayback } from "../util/spotify-ws-api";
  4 | import { debug } from "../util/debug";
  5 | import { SpotifyCluster } from "../types/SpotifyCluster";
  6 | import { ClusterObserver } from "./ClusterObserver";
  7 | 
  8 | /**
  9 |  * Default coordinator for the initialization of a Spotify socket following a successful connection
 10 |  */
 11 | export class CoordinatedSpotifySocket extends SpotifySocket {
 12 |     /**
 13 |      * Creates a coordinated socket from the given cookies and SpotifyDevice
 14 |      * @param cookie cookies from open.spotify.com
 15 |      * @param device device metadata to use when initializing – omit to use default
 16 |      * @returns promise of a CoordinatedSpotifySocket and the accessToken used to create it
 17 |      */
 18 |     public static async create(cookie: string, device?: SpotifyDevice): Promise<{
 19 |         accessToken: string;
 20 |         socket: CoordinatedSpotifySocket;
 21 |     }> {
 22 |         const { accessToken, socket } = await automatedCreateSpotifyClient(cookie);
 23 | 
 24 |         return {
 25 |             accessToken,
 26 |             socket: new CoordinatedSpotifySocket(socket, accessToken, cookie, device)
 27 |         };
 28 |     }
 29 | 
 30 |     /**
 31 |      * Default device metadata. The device_id is randomized at runtime.
 32 |      * 
 33 |      * This object is sealed. If you need to mutate it, make your own.
 34 |      */
 35 |     public static readonly DEFAULT_DEVICE: SpotifyDevice = Object.seal({
 36 |         brand: "spotify",
 37 |         capabilities: {
 38 |             audio_podcasts: true,
 39 |             change_volume: true,
 40 |             disable_connect: false,
 41 |             enable_play_token: true,
 42 |             manifest_formats: [
 43 |                 "file_urls_mp3",
 44 |                 "manifest_ids_video",
 45 |                 "file_urls_external",
 46 |                 "file_ids_mp4",
 47 |                 "file_ids_mp4_dual"
 48 |             ],
 49 |             play_token_lost_behavior: "pause",
 50 |             supports_file_media_type: true,
 51 |             video_playback: true
 52 |         },
 53 |         device_id: Array(40).fill(0).map(x => Math.random().toString(36).charAt(2)).join(''),
 54 |         device_type: "computer",
 55 |         metadata: {},
 56 |         model: "web_player",
 57 |         name: "Web Player (Microsoft Edge)",
 58 |         platform_identifier: "web_player osx 11.3.0;microsoft edge 89.0.774.54;desktop"
 59 |     });
 60 | 
 61 |     #lastCluster: SpotifyCluster;
 62 | 
 63 |     private constructor(socket: WebSocket, accessToken: string, cookie: string, public readonly device: SpotifyDevice = CoordinatedSpotifySocket.DEFAULT_DEVICE) {
 64 |         super(socket);
 65 | 
 66 |         this.#accessToken = accessToken;
 67 |         this.#cookie = cookie;
 68 | 
 69 |         debug(`create CoordinatedSpotifySocket: ${socket.readyState}`)
 70 | 
 71 |         socket.onclose = async () => {
 72 |             debug("disconnected from spotify.");
 73 | 
 74 |             if (this.#forceClosed) return;
 75 |             
 76 |             debug("scheduling reconnect");
 77 |             await new Promise(resolve => setTimeout(resolve, 5000));
 78 | 
 79 |             debug("reconnecting to spotify");
 80 |             const { accessToken, socket } = await automatedCreateSpotifyClient(cookie);
 81 | 
 82 |             this.#accessToken = accessToken;
 83 |             this.attach(socket);
 84 |         };
 85 | 
 86 |         new ClusterObserver(clusters => {
 87 |             this.#lastCluster = clusters[0];
 88 |         }).observe(this);
 89 | 
 90 |         this.observeConnectionID(async connectionID => {
 91 |             if (connectionID) {
 92 |                 // await subscribeToNotifications(connectionID, this.#accessToken);
 93 |                 await trackPlayback(connectionID, this.#accessToken, this.device);
 94 |                 const cluster = this.#lastCluster = await connectState(connectionID, this.#accessToken, device);
 95 | 
 96 |                 debug("we are connected to spotify.");
 97 | 
 98 |                 this.handlePayload({
 99 |                     headers: {
100 |                         "content-type": "application/json"
101 |                     },
102 |                     payloads: [
103 |                         {
104 |                             ack_id: "none",
105 |                             cluster,
106 |                             devices_that_changed: [cluster.active_device_id],
107 |                             update_reason: "INITIAL_STATE"
108 |                         }
109 |                     ],
110 |                     type: "message",
111 |                     uri: "hm://connect-state/v1/cluster"
112 |                 });
113 |             }
114 |         });
115 |     }
116 | 
117 |     #accessToken: string;
118 |     #cookie: string;
119 |     #forceClosed: boolean = false;
120 | 
121 |     public close() {
122 |         this.#forceClosed = true;
123 |         this.socket.close();
124 |         this.halt();
125 |     }
126 | 
127 |     public async generateAccessToken(): Promise<string> {
128 |         const { accessToken } = await getAccessToken(this.#cookie);
129 |         return this.#accessToken = accessToken;
130 |     }
131 | 
132 |     public get accessTokenRegenerator(): SpotifyAccessTokenRegnerator {
133 |         return () => this.generateAccessToken();
134 |     }
135 | 
136 |     public async sendCommand(endpoint: string, opts: any = {}): Promise<void> {
137 |         const activeDevice = this.#lastCluster?.active_device_id;
138 | 
139 |         if (!activeDevice) return;
140 | 
141 |         await sendCommand({
142 |             from: this.device.device_id,
143 |             to: activeDevice,
144 |             endpoint,
145 |             accessToken: this.#accessToken,
146 |             opts
147 |         });
148 |     }
149 | }


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     /* Visit https://aka.ms/tsconfig.json to read more about this file */
 4 | 
 5 |     /* Basic Options */
 6 |     // "incremental": true,                   /* Enable incremental compilation */
 7 |     "target": "ES2019",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
 8 |     "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
 9 |     // "lib": [],                             /* Specify library files to be included in the compilation. */
10 |     // "allowJs": true,                       /* Allow javascript files to be compiled. */
11 |     // "checkJs": true,                       /* Report errors in .js files. */
12 |     // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
13 |     "declaration": true,                   /* Generates corresponding '.d.ts' file. */
14 |     "declarationMap": false,                /* Generates a sourcemap for each corresponding '.d.ts' file. */
15 |     "sourceMap": false,                     /* Generates corresponding '.map' file. */
16 |     // "outFile": "./",                       /* Concatenate and emit output to single file. */
17 |     "outDir": "./dist",                        /* Redirect output structure to the directory. */
18 |     "rootDir": "./src",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
19 |     // "composite": true,                     /* Enable project compilation */
20 |     // "tsBuildInfoFile": "./",               /* Specify file to store incremental compilation information */
21 |     // "removeComments": true,                /* Do not emit comments to output. */
22 |     // "noEmit": true,                        /* Do not emit outputs. */
23 |     // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
24 |     // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
25 |     // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
26 | 
27 |     /* Strict Type-Checking Options */
28 |     "strict": true,                           /* Enable all strict type-checking options. */
29 |     // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
30 |     // "strictNullChecks": true,              /* Enable strict null checks. */
31 |     // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
32 |     // "strictBindCallApply": true,           /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
33 |     "strictPropertyInitialization": false,  /* Enable strict checking of property initialization in classes. */
34 |     // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
35 |     // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */
36 | 
37 |     /* Additional Checks */
38 |     // "noUnusedLocals": true,                /* Report errors on unused locals. */
39 |     // "noUnusedParameters": true,            /* Report errors on unused parameters. */
40 |     // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
41 |     // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */
42 | 
43 |     /* Module Resolution Options */
44 |     "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
45 |     // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
46 |     // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
47 |     // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
48 |     // "typeRoots": [],                       /* List of folders to include type definitions from. */
49 |     // "types": [],                           /* Type declaration files to be included in compilation. */
50 |     // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
51 |     "esModuleInterop": true,                  /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
52 |     // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
53 |     // "allowUmdGlobalAccess": true,          /* Allow accessing UMD globals from modules. */
54 | 
55 |     /* Source Map Options */
56 |     // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
57 |     // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
58 |     // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
59 |     // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
60 | 
61 |     /* Experimental Options */
62 |     "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
63 |     "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
64 | 
65 |     /* Advanced Options */
66 |     "skipLibCheck": true,                     /* Skip type checking of declaration files. */
67 |     "forceConsistentCasingInFileNames": true  /* Disallow inconsistently-cased references to the same file. */,
68 |     "resolveJsonModule": true
69 |   }
70 | }
71 | 


--------------------------------------------------------------------------------
/src/util/spotify-ws-api.ts:
--------------------------------------------------------------------------------
  1 | import axios from "axios";
  2 | import WebSocket from "isomorphic-ws";
  3 | import { SpotifyCluster } from "../types/SpotifyCluster";
  4 | import { CORE_HEADERS } from "./const";
  5 | import { debug } from "./debug";
  6 | 
  7 | export interface AccessToken {
  8 |     accessToken: string;
  9 |     accessTokenExpirationTimestampMs: number;
 10 |     clientId: string;
 11 |     isAnonymous: boolean;
 12 | }
 13 | 
 14 | async function getAccessToken_asScrape(cookie: string): Promise<AccessToken> {
 15 |     // /<script[^>]id="config"[^>]*>(.*)<\/script><script id="baba"/
 16 |     const { data } = await axios.get<string>("https://open.spotify.com/", {
 17 |         headers: {
 18 |             cookie,
 19 |             ...CORE_HEADERS
 20 |         },
 21 |         responseType: "text"
 22 |     });
 23 | 
 24 |     return JSON.parse(/<script[^>]id="config"[^>]*>(.*)<\/script><script id="baba"/.exec(data)![1]);
 25 | }
 26 | 
 27 | /**
 28 |  * Gets an access token for connecting to the WebSocket server
 29 |  * @param cookie cookies from open.spotify.com
 30 |  * @returns the access token generation payload
 31 |  */
 32 | export async function getAccessToken(cookie: string): Promise<AccessToken> {
 33 |     if (1) {
 34 |         return getAccessToken_asScrape(cookie);
 35 |     }
 36 | 
 37 |     const { data } = await axios.get<AccessToken>("https://open.spotify.com/get_access_token?reason=transport&productType=web_player", {
 38 |         headers: {
 39 |             cookie,
 40 |             ...CORE_HEADERS,
 41 |             referer: "https://accounts.spotify.com/"
 42 |         }
 43 |     });
 44 | 
 45 |     return data;
 46 | }
 47 | 
 48 | export interface DiscoveryResult {
 49 |     /**
 50 |      * Array of dealers in the format {HOSTNAME}:{PORT}
 51 |      */
 52 |     dealer: string[];
 53 |     /**
 54 |      * Array of spclient URLs in the format {HOSTNAME}:{PORT}
 55 |      */
 56 |     spclient: string[];
 57 | }
 58 | 
 59 | const DEALER_DISCOVERY_HEADERS = {
 60 |     ...CORE_HEADERS,
 61 |     origin: "https://open.spotify.com"
 62 | }
 63 | 
 64 | /**
 65 |  * Resolves the dealers currently provided by Spotify
 66 |  * @returns dealer discovery payload
 67 |  */
 68 | export async function discoverDealers(): Promise<DiscoveryResult> {
 69 |     const { data } = await axios.get<DiscoveryResult>("https://apresolve.spotify.com/?type=dealer&type=spclient", {
 70 |         headers: DEALER_DISCOVERY_HEADERS
 71 |     });
 72 | 
 73 |     return data;
 74 | }
 75 | 
 76 | /**
 77 |  * Creates a WebSocket connection from the given array of dealers and access token
 78 |  * @param dealers dealers Spotify is offering
 79 |  * @param accessToken WebSocket token
 80 |  * @returns raw WebSocket connection
 81 |  */
 82 | export function createSpotifySocket(dealers: string[], accessToken: string) {
 83 |     const [ dealer ] = dealers;
 84 |     const [ dealerHost, port ] = dealer.split(":");
 85 | 
 86 |     const protocol = port === "443" ? "wss" : "ws";
 87 | 
 88 |     return new WebSocket(`${protocol}://${dealerHost}/?access_token=${accessToken}`)
 89 | }
 90 | 
 91 | /**
 92 |  * Automates the process of resolving dealers/accessToken from the cookies, returning a WebSocket connection
 93 |  * @param cookie cookies from open.spotify.com
 94 |  * @returns a promise of a raw WebSocket connection, and the access token used to create it
 95 |  */
 96 | export async function automatedCreateSpotifyClient(cookie: string): Promise<{
 97 |     accessToken: string;
 98 |     socket: WebSocket;
 99 | }> {
100 |     const { dealer } = await discoverDealers();
101 |     const { accessToken } = await getAccessToken(cookie);
102 | 
103 |     return {
104 |         accessToken,
105 |         socket: createSpotifySocket(dealer, accessToken)
106 |     };
107 | }
108 | 
109 | /**
110 |  * Metadata required when registering a device with Spotify
111 |  */
112 | export interface SpotifyDevice {
113 |     /**
114 |      * The brand of the device (e.g. Spotify, Sonos, etc.)
115 |      */
116 |     brand: string;
117 |     capabilities: {
118 |         audio_podcasts: boolean;
119 |         change_volume: boolean;
120 |         disable_connect: boolean;
121 |         enable_play_token: boolean;
122 |         manifest_formats: string[];
123 |         play_token_lost_behavior: string;
124 |         supports_file_media_type: boolean;
125 |         video_playback: boolean;
126 |     };
127 |     device_id: string;
128 |     device_type: string;
129 |     metadata: Record<string, string>;
130 |     model: string;
131 |     name: string;
132 |     platform_identifier: string;
133 | }
134 | 
135 | /**
136 |  * Subscribes a connection to notifications for a user
137 |  * @param connectionID ID of the connection to subscribe
138 |  * @param accessToken token representing the user to subscribe to
139 |  */
140 | export async function subscribeToNotifications(connectionID: string, accessToken: string): Promise<void> {
141 |     await axios.put(`https://api.spotify.com/v1/me/notifications/user?connection_id=${escape(connectionID)}`, undefined, {
142 |         headers: {
143 |             ...CORE_HEADERS,
144 |             authorization: `Bearer ${accessToken}`
145 |         }
146 |     });
147 | }
148 | 
149 | 
150 | export async function trackPlayback(connectionID: string, accessToken: string, device: SpotifyDevice): Promise<void> {
151 |     await axios.post("https://guc-spclient.spotify.com/track-playback/v1/devices", {
152 |         client_version: "harmony:4.21.0-a4bc573",
153 |         connection_id: connectionID,
154 |         device,
155 |         outro_endcontent_snooping: false,
156 |         volume: 65535
157 |     }, {
158 |         headers: {
159 |             ...CORE_HEADERS,
160 |             origin: "https://open.spotify.com",
161 |             authorization: `Bearer ${accessToken}`
162 |         }
163 |     });
164 | }
165 | 
166 | /**
167 |  * Connects the cluster state to a connection
168 |  * @param connectionID ID of the connection to connect
169 |  * @param accessToken token representing the user to connect to
170 |  * @param device device associated to the connection
171 |  */
172 | export async function connectState(connectionID: string, accessToken: string, device: SpotifyDevice): Promise<SpotifyCluster> {
173 |     const { data } = await axios.put<SpotifyCluster>(`https://guc3-spclient.spotify.com/connect-state/v1/devices/hobs_${device.device_id}`, {
174 |         device: {
175 |             device_info: {
176 |                 capabilities: {
177 |                     can_be_player: false,
178 |                     hidden: true,
179 |                     needs_full_player_state: true
180 |                 }
181 |             }
182 |         },
183 |         member_type: "CONNECT_STATE"
184 |     }, {
185 |         headers: {
186 |             ...CORE_HEADERS,
187 |             authorization: `Bearer ${accessToken}`,
188 |             "x-spotify-connection-id": connectionID
189 |         }
190 |     });
191 | 
192 |     return data;
193 | }
194 | 
195 | export interface SpotifyCommandOptions {
196 |     from: string;
197 |     to: string;
198 |     endpoint: string;
199 |     accessToken: string;
200 |     opts?: any;
201 | }
202 | 
203 | export async function sendCommand({ from, accessToken, to, endpoint, opts = {} }: SpotifyCommandOptions) {
204 |     await axios.post(`https://guc-spclient.spotify.com/connect-state/v1/player/command/from/${from}/to/${to}`, {
205 |         command: {
206 |             endpoint,
207 |             ...opts
208 |         }
209 |     }, {
210 |         headers: {
211 |             ...CORE_HEADERS,
212 |             authorization: `Bearer ${accessToken}`
213 |         }
214 |     });
215 | }


--------------------------------------------------------------------------------
/src/structs/AudioAnalysisEvents.ts:
--------------------------------------------------------------------------------
  1 | import EventEmitter from "eventemitter3";
  2 | import { TypedEventEmitter } from "../types/internal/TypedEventEmitter";
  3 | import { Observer } from "../types/Observer";
  4 | import { SpotifyAnalysisResult, SpotifyAnalysisSection, SpotifyAnalysisSegment, SpotifyAnalysisTimeInterval } from "../types/SpotifyAnalysis";
  5 | import { SpotifyPlayerState } from "../types/SpotifyCluster";
  6 | import { AudioAnalysisCallback, AudioAnalysisObserver, AudioAnalysisObserverOptions } from "./AudioAnalysisObserver";
  7 | import { SpotifySocket } from "./SpotifySocket";
  8 | import { playerStatePosition } from "../util/spotify-player-state";
  9 | 
 10 | interface Events {
 11 |     tatum: SpotifyAnalysisTimeInterval;
 12 |     segment: SpotifyAnalysisSegment;
 13 |     section: SpotifyAnalysisSection;
 14 |     beat: SpotifyAnalysisTimeInterval;
 15 |     bar: SpotifyAnalysisTimeInterval;
 16 |     change: SpotifyAnalysisResult;
 17 | }
 18 | 
 19 | export interface AudioAnalysisDiscriminator {
 20 |     (states: Parameters<AudioAnalysisCallback>[0]): Parameters<AudioAnalysisCallback>[0][0];
 21 | }
 22 | 
 23 | export interface AudioAnalysisEventsOptions extends AudioAnalysisObserverOptions {
 24 |     discriminator?: AudioAnalysisDiscriminator;
 25 | }
 26 | 
 27 | type DamnitTimeout = ReturnType<typeof setTimeout>;
 28 | 
 29 | const events: (keyof AudioAnalysisEvents)[] = [
 30 |     "tatum",
 31 |     "segment",
 32 |     "section",
 33 |     "beat",
 34 |     "bar"
 35 | ];
 36 | 
 37 | /**
 38 |  * Emits events when certain components of the current song are reached
 39 |  */
 40 | export class AudioAnalysisEvents extends (EventEmitter as TypedEventEmitter<Events>) implements Observer<SpotifySocket> {
 41 |     public constructor(options: AudioAnalysisEventsOptions) {
 42 |         super();
 43 |         
 44 |         this.#discriminator = options.discriminator || (states => states[0])
 45 | 
 46 |         this.#observer = new AudioAnalysisObserver(states => {
 47 |             const [ analysis, state ] = this.#discriminator(states);
 48 | 
 49 |             this.#current = analysis;
 50 |             this.#playerState = state;
 51 | 
 52 |             this.emit("change", this.#current);
 53 | 
 54 |             this.killall();
 55 | 
 56 |             if (state.is_playing && !state.is_paused) this.reschedule();
 57 |         }, options);
 58 |     }
 59 | 
 60 |     #observer: AudioAnalysisObserver;
 61 |     #discriminator: AudioAnalysisDiscriminator;
 62 |     #current: SpotifyAnalysisResult | null = null;
 63 |     #playerState: SpotifyPlayerState | null = null;
 64 |     #pending: Record<keyof this, DamnitTimeout | undefined> = {} as Record<keyof this, DamnitTimeout | undefined>;
 65 | 
 66 |     /**
 67 |      * De-schedules all pending analysis updates
 68 |      * @private
 69 |      */
 70 |     private killall() {
 71 |         events.forEach(key => this.#pending[key] && clearTimeout(this.#pending[key]!));
 72 |     }
 73 | 
 74 |     /**
 75 |      * Schedules analysis updates
 76 |      * @private
 77 |      */
 78 |     private reschedule() {
 79 |         events.forEach(key => this.run(key));
 80 |     }
 81 | 
 82 |     /**
 83 |      * Runs an analysis update
 84 |      * @param key key of the analysis to update
 85 |      */
 86 |     public run(key: keyof this) {
 87 |         if (this.#pending[key]) this.#pending[key] = clearTimeout(this.#pending[key]!) as undefined;
 88 | 
 89 |         const { [key]: interval } = this;
 90 | 
 91 |         if (!interval || !SpotifyAnalysisTimeInterval.isInterval(interval)) {
 92 |             this.defer(key);
 93 |             return;
 94 |         };
 95 | 
 96 |         this.emit(key as keyof Events, interval);
 97 | 
 98 |         this.#pending[key] = setTimeout(() => {
 99 |             this.#pending[key] = undefined;
100 |             this.run(key);
101 |         }, this.remainingMSInInterval(interval));
102 |     }
103 | 
104 |     /**
105 |      * Defers an update for an analysis component
106 |      * @param key key of the analysis to defer
107 |      */
108 |     private defer(key: keyof this) {
109 |         if (this.#pending[key]) this.#pending[key] = clearTimeout(this.#pending[key]!) as undefined;
110 | 
111 |         this.#pending[key] = setTimeout(() => {
112 |             this.#pending[key] = undefined;
113 |             this.run(key);
114 |         }, 1000);
115 |     }
116 | 
117 |     /**
118 |      * Returns the remaining milliseconds in a time interval, relative to the current position
119 |      * @param param0 
120 |      * @returns 
121 |      */
122 |     public remainingMSInInterval({ start, duration }: SpotifyAnalysisTimeInterval): number {
123 |         return ((start + duration) - this.position) * 1000;
124 |     }
125 | 
126 |     public observe(target: SpotifySocket) {
127 |         this.#observer.observe(target);
128 |     }
129 | 
130 |     public unobserve(target: SpotifySocket) {
131 |         this.#observer.unobserve(target);
132 |     }
133 | 
134 |     public disconnect() {
135 |         this.#observer.disconnect();
136 |     }
137 | 
138 |     public get playerState(): SpotifyPlayerState | null {
139 |         return this.#playerState;
140 |     }
141 | 
142 |     public get current(): SpotifyAnalysisResult | null {
143 |         return this.#current;
144 |     }
145 | 
146 |     /**
147 |      * Whether the song basically just started
148 |      */
149 |     private get isCloseToStart(): boolean {
150 |         return this.position < 2;
151 |     }
152 | 
153 |     /**
154 |      * Current tatum
155 |      */
156 |     public get tatum(): SpotifyAnalysisTimeInterval | null {
157 |         if (!this.#current) return null;
158 | 
159 |         if (this.isCloseToStart) return this.#current.tatums[0];
160 | 
161 |         return this.#current.tatums.find(({ start }) => start < this.position) || null;
162 |     }
163 | 
164 |     /**
165 |      * Index of the current segment
166 |      */
167 |     private get segmentIndex(): number {
168 |         if (!this.#current) return -1;
169 | 
170 |         if (this.isCloseToStart) return 0;
171 | 
172 |         return this.#current.segments.findIndex(({ start }) => start < this.position);
173 |     }
174 | 
175 |     /**
176 |      * Current segment
177 |      */
178 |     public get segment(): SpotifyAnalysisSegment | null {
179 |         return this.#current?.segments[this.segmentIndex] || null;
180 |     }
181 | 
182 |     /**
183 |      * Next segment
184 |      */
185 |     public get nextSegment(): SpotifyAnalysisSegment | null {
186 |         return this.#current?.segments[this.segmentIndex - 1] || null;
187 |     }
188 | 
189 |     /**
190 |      * Segment after next segment
191 |      */
192 |     public get secondNextSegment(): SpotifyAnalysisSegment | null {
193 |         return this.#current?.segments[this.segmentIndex - 2] || null;
194 |     }
195 | 
196 |     /**
197 |      * Current section
198 |      */
199 |     public get section(): SpotifyAnalysisSection | null {
200 |         if (!this.#current) return null;
201 | 
202 |         if (this.isCloseToStart) return this.#current.sections[0];
203 | 
204 |         return this.#current.sections.find(({ start }) => start < this.position) || null;
205 |     }
206 | 
207 |     /**
208 |      * Current beat
209 |      */
210 |     public get beat(): SpotifyAnalysisTimeInterval | null {
211 |         return this.#current?.beats.find(({ start }) => start < this.position) || null;
212 |     }
213 | 
214 |     /**
215 |      * Current bar
216 |      */
217 |     public get bar(): SpotifyAnalysisTimeInterval | null {
218 |         if (!this.#current) return null;
219 | 
220 |         if (this.isCloseToStart) return this.#current.bars[0];
221 | 
222 |         return this.#current.bars.find(({ start }) => start >= this.position) || null;
223 |     }
224 | 
225 |     /**
226 |      * Current track position
227 |      */
228 |     public get position(): number {
229 |         if (!this.#playerState) return NaN;
230 |         return playerStatePosition(this.#playerState);
231 |     }
232 | }


--------------------------------------------------------------------------------
/src/structs/SpotifySocket.ts:
--------------------------------------------------------------------------------
  1 | import WebSocket from "isomorphic-ws";
  2 | import { debug } from "../util/debug";
  3 | import { automatedCreateSpotifyClient } from "../util/spotify-ws-api";
  4 | 
  5 | export type SpotifyPayloadType = "ping" | "pong" | "message";
  6 | 
  7 | interface SpotifyPayload<Type extends SpotifyPayloadType> {
  8 |     type: Type;
  9 | }
 10 | 
 11 | export type SpotifyPingPayload = SpotifyPayload<"ping">;
 12 | export type SpotifyPongPayload = SpotifyPayload<"pong">;
 13 | 
 14 | /**
 15 |  * Encompasses all actual messages being sent my Spotify that isn't a ping/pong
 16 |  */
 17 | export interface SpotifyMessagePayload extends SpotifyPayload<"message"> {
 18 |     headers: Record<string, string>;
 19 |     payloads: unknown[];
 20 |     method?: string;
 21 |     uri: string;
 22 | }
 23 | 
 24 | export interface SpotifyPayloadMap {
 25 |     ping: SpotifyPingPayload;
 26 |     pong: SpotifyPongPayload;
 27 |     message: SpotifyMessagePayload;
 28 | }
 29 | 
 30 | export type AnySpotifyPayload = SpotifyPayloadMap[keyof SpotifyPayloadMap];
 31 | 
 32 | const SPOTIFY_PING_INTERVAL = 30000;
 33 | 
 34 | /**
 35 |  * Same as a SpotifyMessagePayload, but with the URI parsed to improve routing
 36 |  */
 37 | export interface ParsedSpotifyMessage extends SpotifyMessagePayload {
 38 |     /**
 39 |      * The API this message is being routed to.
 40 |      * 
 41 |      * Given hm://track-playback/v1/command, the API would be track-playback
 42 |      */
 43 |     api: string;
 44 |     /**
 45 |      * The path this message is hitting.
 46 |      * 
 47 |      * Given hm://track-playback/v1/command, the path would be /v1/command
 48 |      */
 49 |     path: string;
 50 |     /**
 51 |      * The components of the path this message is hitting.
 52 |      * 
 53 |      * Given hm://track-playback/v1/command, the components would be ["v1", "command"]
 54 |      */
 55 |     pathComponents: string[];
 56 |     /**
 57 |      * The underlying URL used to parse this message
 58 |      */
 59 |     url: URL;
 60 | }
 61 | 
 62 | export interface SpotifyMessageHandler {
 63 |     (message: ParsedSpotifyMessage): any;
 64 | }
 65 | 
 66 | export interface SpotifyConnectionIDObserver {
 67 |     (connectionID: string | null): any;
 68 | }
 69 | 
 70 | export interface SpotifyAccessTokenRegnerator {
 71 |     (): Promise<string>;
 72 | }
 73 | 
 74 | /**
 75 |  * 
 76 |  */
 77 | export abstract class SpotifySocket {
 78 |     /**
 79 |      * Constructs a Spotify socket from the given open.spotify.com cookies
 80 |      * @param cookie cookies you got
 81 |      * @returns a promise of a SpotifySocket, and the access token used to create it
 82 |      */
 83 |     public static async create(cookie: string): Promise<{
 84 |         accessToken: string;
 85 |         socket: SpotifySocket;
 86 |     }> {
 87 |         throw new Error("This must be overridden by an implementing class.");
 88 |     }
 89 | 
 90 |     /**
 91 |      * Constructs a SpotifySocket instance from an underlying WebSocket connection
 92 |      * @param socket connection to Spotify
 93 |      */
 94 |     public constructor(socket: WebSocket) {
 95 |         this.attach(socket);
 96 |     }
 97 | 
 98 |     #handlers: Map<string, Set<SpotifyMessageHandler>> = new Map();
 99 |     #connectionIDObservers: Set<SpotifyConnectionIDObserver> = new Set();
100 |     #connectionID: string | null = null;
101 |     #startedPing: boolean = false;
102 |     #socket: WebSocket;
103 | 
104 |     /**
105 |      * Generates a refreshed access token
106 |      */
107 |     public abstract generateAccessToken(): Promise<string>;
108 | 
109 |     /**
110 |      * Bound function that can be passed to regnerate the token
111 |      */
112 |     public abstract get accessTokenRegenerator(): SpotifyAccessTokenRegnerator;
113 | 
114 |     public attach(socket: WebSocket) {
115 |         if (this.#socket?.readyState !== this.#socket?.CLOSED) throw new Error("Cannot attach to multiple sockets.");
116 | 
117 |         this.#socket = socket;
118 | 
119 |         socket.onmessage = ({ data }) => this.handlePayload(JSON.parse(data.toString()));
120 | 
121 |         this.registerHandler("pusher", ({ path, pathComponents, headers }) => {
122 |             switch (pathComponents.slice(0, 3).join("/")) {
123 |                 case "/v1/connections":
124 |                     this.#connectionID = headers["Spotify-Connection-Id"] || null;
125 |                     this.#connectionIDObservers.forEach(observer => observer(this.#connectionID));
126 |                     if (!this.#startedPing) {
127 |                         this.ping();
128 |                         this.#startedPing = true;
129 |                     }
130 |                     break;
131 |             }
132 |         });
133 |     }
134 | 
135 |     /**
136 |      * Subscribe to changes to the Spotify connection ID
137 |      * @param observer callback function to receive changes
138 |      */
139 |     public observeConnectionID(observer: SpotifyConnectionIDObserver) {
140 |         this.#connectionIDObservers.add(observer);
141 |     }
142 | 
143 |     /**
144 |      * Unsubscribe from changes to the Spotify connection ID
145 |      * @param observer callback function to unsubscribe changes
146 |      */
147 |     public unobserveConnectionID(observer: SpotifyConnectionIDObserver) {
148 |         this.#connectionIDObservers.delete(observer);
149 |     }
150 | 
151 |     /**
152 |      * Registers a handler for the given API scope
153 |      * @param api api scope
154 |      * @param handler callback function for messages within this api
155 |      */
156 |     public registerHandler(api: string, handler: SpotifyMessageHandler) {
157 |         const handlers = this.#handlers.get(api) || this.#handlers.set(api, new Set()).get(api)!;
158 |         handlers.add(handler);
159 |     }
160 | 
161 |     /**
162 |      * Unregesters a handler from the given API scope
163 |      * @param api api scope
164 |      * @param handler callback function to unregister
165 |      */
166 |     public unregisterHandler(api: string, handler: SpotifyMessageHandler) {
167 |         const handlers = this.#handlers.get(api);
168 |         if (handlers) {
169 |             handlers.delete(handler);
170 |             if (!handlers.size) this.#handlers.delete(api);
171 |         }
172 |     }
173 | 
174 |     /**
175 |      * Spotify WebSocket connection ID
176 |      */
177 |     public get connectionID(): string | null {
178 |         return this.#connectionID;
179 |     }
180 | 
181 |     public get socket(): WebSocket {
182 |         return this.#socket;
183 |     }
184 | 
185 |     /**
186 |      * Handles an incoming payload from Spotify
187 |      * @param payload payload received from Spotify
188 |      * @private
189 |      */
190 |     protected handlePayload(payload: AnySpotifyPayload) {
191 |         switch (payload.type) {
192 |             case "pong":
193 |                 debug("spotify ponged us");
194 |                 this.deferredPing();
195 |                 break;
196 |             case "message":
197 |                 try {
198 |                     var url = new URL(payload.uri);
199 |                 } catch {
200 |                     var url = new URL(`hm://${payload.uri}`);
201 |                 }
202 | 
203 |                 debug(`message: ${url}`)
204 |                 
205 |                 const handlers = this.#handlers.get(url.hostname);
206 |                 if (!handlers) break;
207 | 
208 |                 const message: ParsedSpotifyMessage = {
209 |                     ...payload,
210 |                     api: url.hostname,
211 |                     path: url.pathname,
212 |                     pathComponents: url.pathname.split("/"),
213 |                     url
214 |                 }
215 |                 handlers.forEach(handler => handler(message));
216 | 
217 |                 break;
218 |             default:
219 |                 debug("unexpected payload received: %s", payload.type);
220 |         }
221 |     }
222 | 
223 |     /**
224 |      * Sends a payload to Spotify
225 |      * @param payload payload to send
226 |      * @private
227 |      */
228 |     private send(payload: AnySpotifyPayload) {
229 |         debug("sending %s", payload.type);
230 |         this.socket.send(JSON.stringify(payload));
231 |     }
232 | 
233 |     /**
234 |      * Sends a ping payload to Spotify
235 |      * @private
236 |      */
237 |     private ping() {
238 |         this.send({ type: "ping" });
239 |     }
240 | 
241 |     /**
242 |      * Schedules a ping to go to Spotify after the SPOTIFY_PING_INTERVAL
243 |      * @private
244 |      */
245 |     #pendingPing: ReturnType<typeof setTimeout>;
246 |     private deferredPing() {
247 |         debug("scheduling deferred ping with interval %d", SPOTIFY_PING_INTERVAL);
248 |         this.#pendingPing = setTimeout(() => this.ping(), SPOTIFY_PING_INTERVAL);
249 |     }
250 | 
251 |     halt() {
252 |         clearTimeout(this.#pendingPing);
253 |         this.#handlers.clear();
254 |     }
255 | }


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 |                     GNU GENERAL PUBLIC LICENSE
  2 |                        Version 3, 29 June 2007
  3 | 
  4 |  Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  5 |  Everyone is permitted to copy and distribute verbatim copies
  6 |  of this license document, but changing it is not allowed.
  7 | 
  8 |                             Preamble
  9 | 
 10 |   The GNU General Public License is a free, copyleft license for
 11 | software and other kinds of works.
 12 | 
 13 |   The licenses for most software and other practical works are designed
 14 | to take away your freedom to share and change the works.  By contrast,
 15 | the GNU General Public License is intended to guarantee your freedom to
 16 | share and change all versions of a program--to make sure it remains free
 17 | software for all its users.  We, the Free Software Foundation, use the
 18 | GNU General Public License for most of our software; it applies also to
 19 | any other work released this way by its authors.  You can apply it to
 20 | your programs, too.
 21 | 
 22 |   When we speak of free software, we are referring to freedom, not
 23 | price.  Our General Public Licenses are designed to make sure that you
 24 | have the freedom to distribute copies of free software (and charge for
 25 | them if you wish), that you receive source code or can get it if you
 26 | want it, that you can change the software or use pieces of it in new
 27 | free programs, and that you know you can do these things.
 28 | 
 29 |   To protect your rights, we need to prevent others from denying you
 30 | these rights or asking you to surrender the rights.  Therefore, you have
 31 | certain responsibilities if you distribute copies of the software, or if
 32 | you modify it: responsibilities to respect the freedom of others.
 33 | 
 34 |   For example, if you distribute copies of such a program, whether
 35 | gratis or for a fee, you must pass on to the recipients the same
 36 | freedoms that you received.  You must make sure that they, too, receive
 37 | or can get the source code.  And you must show them these terms so they
 38 | know their rights.
 39 | 
 40 |   Developers that use the GNU GPL protect your rights with two steps:
 41 | (1) assert copyright on the software, and (2) offer you this License
 42 | giving you legal permission to copy, distribute and/or modify it.
 43 | 
 44 |   For the developers' and authors' protection, the GPL clearly explains
 45 | that there is no warranty for this free software.  For both users' and
 46 | authors' sake, the GPL requires that modified versions be marked as
 47 | changed, so that their problems will not be attributed erroneously to
 48 | authors of previous versions.
 49 | 
 50 |   Some devices are designed to deny users access to install or run
 51 | modified versions of the software inside them, although the manufacturer
 52 | can do so.  This is fundamentally incompatible with the aim of
 53 | protecting users' freedom to change the software.  The systematic
 54 | pattern of such abuse occurs in the area of products for individuals to
 55 | use, which is precisely where it is most unacceptable.  Therefore, we
 56 | have designed this version of the GPL to prohibit the practice for those
 57 | products.  If such problems arise substantially in other domains, we
 58 | stand ready to extend this provision to those domains in future versions
 59 | of the GPL, as needed to protect the freedom of users.
 60 | 
 61 |   Finally, every program is threatened constantly by software patents.
 62 | States should not allow patents to restrict development and use of
 63 | software on general-purpose computers, but in those that do, we wish to
 64 | avoid the special danger that patents applied to a free program could
 65 | make it effectively proprietary.  To prevent this, the GPL assures that
 66 | patents cannot be used to render the program non-free.
 67 | 
 68 |   The precise terms and conditions for copying, distribution and
 69 | modification follow.
 70 | 
 71 |                        TERMS AND CONDITIONS
 72 | 
 73 |   0. Definitions.
 74 | 
 75 |   "This License" refers to version 3 of the GNU General Public License.
 76 | 
 77 |   "Copyright" also means copyright-like laws that apply to other kinds of
 78 | works, such as semiconductor masks.
 79 | 
 80 |   "The Program" refers to any copyrightable work licensed under this
 81 | License.  Each licensee is addressed as "you".  "Licensees" and
 82 | "recipients" may be individuals or organizations.
 83 | 
 84 |   To "modify" a work means to copy from or adapt all or part of the work
 85 | in a fashion requiring copyright permission, other than the making of an
 86 | exact copy.  The resulting work is called a "modified version" of the
 87 | earlier work or a work "based on" the earlier work.
 88 | 
 89 |   A "covered work" means either the unmodified Program or a work based
 90 | on the Program.
 91 | 
 92 |   To "propagate" a work means to do anything with it that, without
 93 | permission, would make you directly or secondarily liable for
 94 | infringement under applicable copyright law, except executing it on a
 95 | computer or modifying a private copy.  Propagation includes copying,
 96 | distribution (with or without modification), making available to the
 97 | public, and in some countries other activities as well.
 98 | 
 99 |   To "convey" a work means any kind of propagation that enables other
100 | parties to make or receive copies.  Mere interaction with a user through
101 | a computer network, with no transfer of a copy, is not conveying.
102 | 
103 |   An interactive user interface displays "Appropriate Legal Notices"
104 | to the extent that it includes a convenient and prominently visible
105 | feature that (1) displays an appropriate copyright notice, and (2)
106 | tells the user that there is no warranty for the work (except to the
107 | extent that warranties are provided), that licensees may convey the
108 | work under this License, and how to view a copy of this License.  If
109 | the interface presents a list of user commands or options, such as a
110 | menu, a prominent item in the list meets this criterion.
111 | 
112 |   1. Source Code.
113 | 
114 |   The "source code" for a work means the preferred form of the work
115 | for making modifications to it.  "Object code" means any non-source
116 | form of a work.
117 | 
118 |   A "Standard Interface" means an interface that either is an official
119 | standard defined by a recognized standards body, or, in the case of
120 | interfaces specified for a particular programming language, one that
121 | is widely used among developers working in that language.
122 | 
123 |   The "System Libraries" of an executable work include anything, other
124 | than the work as a whole, that (a) is included in the normal form of
125 | packaging a Major Component, but which is not part of that Major
126 | Component, and (b) serves only to enable use of the work with that
127 | Major Component, or to implement a Standard Interface for which an
128 | implementation is available to the public in source code form.  A
129 | "Major Component", in this context, means a major essential component
130 | (kernel, window system, and so on) of the specific operating system
131 | (if any) on which the executable work runs, or a compiler used to
132 | produce the work, or an object code interpreter used to run it.
133 | 
134 |   The "Corresponding Source" for a work in object code form means all
135 | the source code needed to generate, install, and (for an executable
136 | work) run the object code and to modify the work, including scripts to
137 | control those activities.  However, it does not include the work's
138 | System Libraries, or general-purpose tools or generally available free
139 | programs which are used unmodified in performing those activities but
140 | which are not part of the work.  For example, Corresponding Source
141 | includes interface definition files associated with source files for
142 | the work, and the source code for shared libraries and dynamically
143 | linked subprograms that the work is specifically designed to require,
144 | such as by intimate data communication or control flow between those
145 | subprograms and other parts of the work.
146 | 
147 |   The Corresponding Source need not include anything that users
148 | can regenerate automatically from other parts of the Corresponding
149 | Source.
150 | 
151 |   The Corresponding Source for a work in source code form is that
152 | same work.
153 | 
154 |   2. Basic Permissions.
155 | 
156 |   All rights granted under this License are granted for the term of
157 | copyright on the Program, and are irrevocable provided the stated
158 | conditions are met.  This License explicitly affirms your unlimited
159 | permission to run the unmodified Program.  The output from running a
160 | covered work is covered by this License only if the output, given its
161 | content, constitutes a covered work.  This License acknowledges your
162 | rights of fair use or other equivalent, as provided by copyright law.
163 | 
164 |   You may make, run and propagate covered works that you do not
165 | convey, without conditions so long as your license otherwise remains
166 | in force.  You may convey covered works to others for the sole purpose
167 | of having them make modifications exclusively for you, or provide you
168 | with facilities for running those works, provided that you comply with
169 | the terms of this License in conveying all material for which you do
170 | not control copyright.  Those thus making or running the covered works
171 | for you must do so exclusively on your behalf, under your direction
172 | and control, on terms that prohibit them from making any copies of
173 | your copyrighted material outside their relationship with you.
174 | 
175 |   Conveying under any other circumstances is permitted solely under
176 | the conditions stated below.  Sublicensing is not allowed; section 10
177 | makes it unnecessary.
178 | 
179 |   3. Protecting Users' Legal Rights From Anti-Circumvention Law.
180 | 
181 |   No covered work shall be deemed part of an effective technological
182 | measure under any applicable law fulfilling obligations under article
183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
184 | similar laws prohibiting or restricting circumvention of such
185 | measures.
186 | 
187 |   When you convey a covered work, you waive any legal power to forbid
188 | circumvention of technological measures to the extent such circumvention
189 | is effected by exercising rights under this License with respect to
190 | the covered work, and you disclaim any intention to limit operation or
191 | modification of the work as a means of enforcing, against the work's
192 | users, your or third parties' legal rights to forbid circumvention of
193 | technological measures.
194 | 
195 |   4. Conveying Verbatim Copies.
196 | 
197 |   You may convey verbatim copies of the Program's source code as you
198 | receive it, in any medium, provided that you conspicuously and
199 | appropriately publish on each copy an appropriate copyright notice;
200 | keep intact all notices stating that this License and any
201 | non-permissive terms added in accord with section 7 apply to the code;
202 | keep intact all notices of the absence of any warranty; and give all
203 | recipients a copy of this License along with the Program.
204 | 
205 |   You may charge any price or no price for each copy that you convey,
206 | and you may offer support or warranty protection for a fee.
207 | 
208 |   5. Conveying Modified Source Versions.
209 | 
210 |   You may convey a work based on the Program, or the modifications to
211 | produce it from the Program, in the form of source code under the
212 | terms of section 4, provided that you also meet all of these conditions:
213 | 
214 |     a) The work must carry prominent notices stating that you modified
215 |     it, and giving a relevant date.
216 | 
217 |     b) The work must carry prominent notices stating that it is
218 |     released under this License and any conditions added under section
219 |     7.  This requirement modifies the requirement in section 4 to
220 |     "keep intact all notices".
221 | 
222 |     c) You must license the entire work, as a whole, under this
223 |     License to anyone who comes into possession of a copy.  This
224 |     License will therefore apply, along with any applicable section 7
225 |     additional terms, to the whole of the work, and all its parts,
226 |     regardless of how they are packaged.  This License gives no
227 |     permission to license the work in any other way, but it does not
228 |     invalidate such permission if you have separately received it.
229 | 
230 |     d) If the work has interactive user interfaces, each must display
231 |     Appropriate Legal Notices; however, if the Program has interactive
232 |     interfaces that do not display Appropriate Legal Notices, your
233 |     work need not make them do so.
234 | 
235 |   A compilation of a covered work with other separate and independent
236 | works, which are not by their nature extensions of the covered work,
237 | and which are not combined with it such as to form a larger program,
238 | in or on a volume of a storage or distribution medium, is called an
239 | "aggregate" if the compilation and its resulting copyright are not
240 | used to limit the access or legal rights of the compilation's users
241 | beyond what the individual works permit.  Inclusion of a covered work
242 | in an aggregate does not cause this License to apply to the other
243 | parts of the aggregate.
244 | 
245 |   6. Conveying Non-Source Forms.
246 | 
247 |   You may convey a covered work in object code form under the terms
248 | of sections 4 and 5, provided that you also convey the
249 | machine-readable Corresponding Source under the terms of this License,
250 | in one of these ways:
251 | 
252 |     a) Convey the object code in, or embodied in, a physical product
253 |     (including a physical distribution medium), accompanied by the
254 |     Corresponding Source fixed on a durable physical medium
255 |     customarily used for software interchange.
256 | 
257 |     b) Convey the object code in, or embodied in, a physical product
258 |     (including a physical distribution medium), accompanied by a
259 |     written offer, valid for at least three years and valid for as
260 |     long as you offer spare parts or customer support for that product
261 |     model, to give anyone who possesses the object code either (1) a
262 |     copy of the Corresponding Source for all the software in the
263 |     product that is covered by this License, on a durable physical
264 |     medium customarily used for software interchange, for a price no
265 |     more than your reasonable cost of physically performing this
266 |     conveying of source, or (2) access to copy the
267 |     Corresponding Source from a network server at no charge.
268 | 
269 |     c) Convey individual copies of the object code with a copy of the
270 |     written offer to provide the Corresponding Source.  This
271 |     alternative is allowed only occasionally and noncommercially, and
272 |     only if you received the object code with such an offer, in accord
273 |     with subsection 6b.
274 | 
275 |     d) Convey the object code by offering access from a designated
276 |     place (gratis or for a charge), and offer equivalent access to the
277 |     Corresponding Source in the same way through the same place at no
278 |     further charge.  You need not require recipients to copy the
279 |     Corresponding Source along with the object code.  If the place to
280 |     copy the object code is a network server, the Corresponding Source
281 |     may be on a different server (operated by you or a third party)
282 |     that supports equivalent copying facilities, provided you maintain
283 |     clear directions next to the object code saying where to find the
284 |     Corresponding Source.  Regardless of what server hosts the
285 |     Corresponding Source, you remain obligated to ensure that it is
286 |     available for as long as needed to satisfy these requirements.
287 | 
288 |     e) Convey the object code using peer-to-peer transmission, provided
289 |     you inform other peers where the object code and Corresponding
290 |     Source of the work are being offered to the general public at no
291 |     charge under subsection 6d.
292 | 
293 |   A separable portion of the object code, whose source code is excluded
294 | from the Corresponding Source as a System Library, need not be
295 | included in conveying the object code work.
296 | 
297 |   A "User Product" is either (1) a "consumer product", which means any
298 | tangible personal property which is normally used for personal, family,
299 | or household purposes, or (2) anything designed or sold for incorporation
300 | into a dwelling.  In determining whether a product is a consumer product,
301 | doubtful cases shall be resolved in favor of coverage.  For a particular
302 | product received by a particular user, "normally used" refers to a
303 | typical or common use of that class of product, regardless of the status
304 | of the particular user or of the way in which the particular user
305 | actually uses, or expects or is expected to use, the product.  A product
306 | is a consumer product regardless of whether the product has substantial
307 | commercial, industrial or non-consumer uses, unless such uses represent
308 | the only significant mode of use of the product.
309 | 
310 |   "Installation Information" for a User Product means any methods,
311 | procedures, authorization keys, or other information required to install
312 | and execute modified versions of a covered work in that User Product from
313 | a modified version of its Corresponding Source.  The information must
314 | suffice to ensure that the continued functioning of the modified object
315 | code is in no case prevented or interfered with solely because
316 | modification has been made.
317 | 
318 |   If you convey an object code work under this section in, or with, or
319 | specifically for use in, a User Product, and the conveying occurs as
320 | part of a transaction in which the right of possession and use of the
321 | User Product is transferred to the recipient in perpetuity or for a
322 | fixed term (regardless of how the transaction is characterized), the
323 | Corresponding Source conveyed under this section must be accompanied
324 | by the Installation Information.  But this requirement does not apply
325 | if neither you nor any third party retains the ability to install
326 | modified object code on the User Product (for example, the work has
327 | been installed in ROM).
328 | 
329 |   The requirement to provide Installation Information does not include a
330 | requirement to continue to provide support service, warranty, or updates
331 | for a work that has been modified or installed by the recipient, or for
332 | the User Product in which it has been modified or installed.  Access to a
333 | network may be denied when the modification itself materially and
334 | adversely affects the operation of the network or violates the rules and
335 | protocols for communication across the network.
336 | 
337 |   Corresponding Source conveyed, and Installation Information provided,
338 | in accord with this section must be in a format that is publicly
339 | documented (and with an implementation available to the public in
340 | source code form), and must require no special password or key for
341 | unpacking, reading or copying.
342 | 
343 |   7. Additional Terms.
344 | 
345 |   "Additional permissions" are terms that supplement the terms of this
346 | License by making exceptions from one or more of its conditions.
347 | Additional permissions that are applicable to the entire Program shall
348 | be treated as though they were included in this License, to the extent
349 | that they are valid under applicable law.  If additional permissions
350 | apply only to part of the Program, that part may be used separately
351 | under those permissions, but the entire Program remains governed by
352 | this License without regard to the additional permissions.
353 | 
354 |   When you convey a copy of a covered work, you may at your option
355 | remove any additional permissions from that copy, or from any part of
356 | it.  (Additional permissions may be written to require their own
357 | removal in certain cases when you modify the work.)  You may place
358 | additional permissions on material, added by you to a covered work,
359 | for which you have or can give appropriate copyright permission.
360 | 
361 |   Notwithstanding any other provision of this License, for material you
362 | add to a covered work, you may (if authorized by the copyright holders of
363 | that material) supplement the terms of this License with terms:
364 | 
365 |     a) Disclaiming warranty or limiting liability differently from the
366 |     terms of sections 15 and 16 of this License; or
367 | 
368 |     b) Requiring preservation of specified reasonable legal notices or
369 |     author attributions in that material or in the Appropriate Legal
370 |     Notices displayed by works containing it; or
371 | 
372 |     c) Prohibiting misrepresentation of the origin of that material, or
373 |     requiring that modified versions of such material be marked in
374 |     reasonable ways as different from the original version; or
375 | 
376 |     d) Limiting the use for publicity purposes of names of licensors or
377 |     authors of the material; or
378 | 
379 |     e) Declining to grant rights under trademark law for use of some
380 |     trade names, trademarks, or service marks; or
381 | 
382 |     f) Requiring indemnification of licensors and authors of that
383 |     material by anyone who conveys the material (or modified versions of
384 |     it) with contractual assumptions of liability to the recipient, for
385 |     any liability that these contractual assumptions directly impose on
386 |     those licensors and authors.
387 | 
388 |   All other non-permissive additional terms are considered "further
389 | restrictions" within the meaning of section 10.  If the Program as you
390 | received it, or any part of it, contains a notice stating that it is
391 | governed by this License along with a term that is a further
392 | restriction, you may remove that term.  If a license document contains
393 | a further restriction but permits relicensing or conveying under this
394 | License, you may add to a covered work material governed by the terms
395 | of that license document, provided that the further restriction does
396 | not survive such relicensing or conveying.
397 | 
398 |   If you add terms to a covered work in accord with this section, you
399 | must place, in the relevant source files, a statement of the
400 | additional terms that apply to those files, or a notice indicating
401 | where to find the applicable terms.
402 | 
403 |   Additional terms, permissive or non-permissive, may be stated in the
404 | form of a separately written license, or stated as exceptions;
405 | the above requirements apply either way.
406 | 
407 |   8. Termination.
408 | 
409 |   You may not propagate or modify a covered work except as expressly
410 | provided under this License.  Any attempt otherwise to propagate or
411 | modify it is void, and will automatically terminate your rights under
412 | this License (including any patent licenses granted under the third
413 | paragraph of section 11).
414 | 
415 |   However, if you cease all violation of this License, then your
416 | license from a particular copyright holder is reinstated (a)
417 | provisionally, unless and until the copyright holder explicitly and
418 | finally terminates your license, and (b) permanently, if the copyright
419 | holder fails to notify you of the violation by some reasonable means
420 | prior to 60 days after the cessation.
421 | 
422 |   Moreover, your license from a particular copyright holder is
423 | reinstated permanently if the copyright holder notifies you of the
424 | violation by some reasonable means, this is the first time you have
425 | received notice of violation of this License (for any work) from that
426 | copyright holder, and you cure the violation prior to 30 days after
427 | your receipt of the notice.
428 | 
429 |   Termination of your rights under this section does not terminate the
430 | licenses of parties who have received copies or rights from you under
431 | this License.  If your rights have been terminated and not permanently
432 | reinstated, you do not qualify to receive new licenses for the same
433 | material under section 10.
434 | 
435 |   9. Acceptance Not Required for Having Copies.
436 | 
437 |   You are not required to accept this License in order to receive or
438 | run a copy of the Program.  Ancillary propagation of a covered work
439 | occurring solely as a consequence of using peer-to-peer transmission
440 | to receive a copy likewise does not require acceptance.  However,
441 | nothing other than this License grants you permission to propagate or
442 | modify any covered work.  These actions infringe copyright if you do
443 | not accept this License.  Therefore, by modifying or propagating a
444 | covered work, you indicate your acceptance of this License to do so.
445 | 
446 |   10. Automatic Licensing of Downstream Recipients.
447 | 
448 |   Each time you convey a covered work, the recipient automatically
449 | receives a license from the original licensors, to run, modify and
450 | propagate that work, subject to this License.  You are not responsible
451 | for enforcing compliance by third parties with this License.
452 | 
453 |   An "entity transaction" is a transaction transferring control of an
454 | organization, or substantially all assets of one, or subdividing an
455 | organization, or merging organizations.  If propagation of a covered
456 | work results from an entity transaction, each party to that
457 | transaction who receives a copy of the work also receives whatever
458 | licenses to the work the party's predecessor in interest had or could
459 | give under the previous paragraph, plus a right to possession of the
460 | Corresponding Source of the work from the predecessor in interest, if
461 | the predecessor has it or can get it with reasonable efforts.
462 | 
463 |   You may not impose any further restrictions on the exercise of the
464 | rights granted or affirmed under this License.  For example, you may
465 | not impose a license fee, royalty, or other charge for exercise of
466 | rights granted under this License, and you may not initiate litigation
467 | (including a cross-claim or counterclaim in a lawsuit) alleging that
468 | any patent claim is infringed by making, using, selling, offering for
469 | sale, or importing the Program or any portion of it.
470 | 
471 |   11. Patents.
472 | 
473 |   A "contributor" is a copyright holder who authorizes use under this
474 | License of the Program or a work on which the Program is based.  The
475 | work thus licensed is called the contributor's "contributor version".
476 | 
477 |   A contributor's "essential patent claims" are all patent claims
478 | owned or controlled by the contributor, whether already acquired or
479 | hereafter acquired, that would be infringed by some manner, permitted
480 | by this License, of making, using, or selling its contributor version,
481 | but do not include claims that would be infringed only as a
482 | consequence of further modification of the contributor version.  For
483 | purposes of this definition, "control" includes the right to grant
484 | patent sublicenses in a manner consistent with the requirements of
485 | this License.
486 | 
487 |   Each contributor grants you a non-exclusive, worldwide, royalty-free
488 | patent license under the contributor's essential patent claims, to
489 | make, use, sell, offer for sale, import and otherwise run, modify and
490 | propagate the contents of its contributor version.
491 | 
492 |   In the following three paragraphs, a "patent license" is any express
493 | agreement or commitment, however denominated, not to enforce a patent
494 | (such as an express permission to practice a patent or covenant not to
495 | sue for patent infringement).  To "grant" such a patent license to a
496 | party means to make such an agreement or commitment not to enforce a
497 | patent against the party.
498 | 
499 |   If you convey a covered work, knowingly relying on a patent license,
500 | and the Corresponding Source of the work is not available for anyone
501 | to copy, free of charge and under the terms of this License, through a
502 | publicly available network server or other readily accessible means,
503 | then you must either (1) cause the Corresponding Source to be so
504 | available, or (2) arrange to deprive yourself of the benefit of the
505 | patent license for this particular work, or (3) arrange, in a manner
506 | consistent with the requirements of this License, to extend the patent
507 | license to downstream recipients.  "Knowingly relying" means you have
508 | actual knowledge that, but for the patent license, your conveying the
509 | covered work in a country, or your recipient's use of the covered work
510 | in a country, would infringe one or more identifiable patents in that
511 | country that you have reason to believe are valid.
512 | 
513 |   If, pursuant to or in connection with a single transaction or
514 | arrangement, you convey, or propagate by procuring conveyance of, a
515 | covered work, and grant a patent license to some of the parties
516 | receiving the covered work authorizing them to use, propagate, modify
517 | or convey a specific copy of the covered work, then the patent license
518 | you grant is automatically extended to all recipients of the covered
519 | work and works based on it.
520 | 
521 |   A patent license is "discriminatory" if it does not include within
522 | the scope of its coverage, prohibits the exercise of, or is
523 | conditioned on the non-exercise of one or more of the rights that are
524 | specifically granted under this License.  You may not convey a covered
525 | work if you are a party to an arrangement with a third party that is
526 | in the business of distributing software, under which you make payment
527 | to the third party based on the extent of your activity of conveying
528 | the work, and under which the third party grants, to any of the
529 | parties who would receive the covered work from you, a discriminatory
530 | patent license (a) in connection with copies of the covered work
531 | conveyed by you (or copies made from those copies), or (b) primarily
532 | for and in connection with specific products or compilations that
533 | contain the covered work, unless you entered into that arrangement,
534 | or that patent license was granted, prior to 28 March 2007.
535 | 
536 |   Nothing in this License shall be construed as excluding or limiting
537 | any implied license or other defenses to infringement that may
538 | otherwise be available to you under applicable patent law.
539 | 
540 |   12. No Surrender of Others' Freedom.
541 | 
542 |   If conditions are imposed on you (whether by court order, agreement or
543 | otherwise) that contradict the conditions of this License, they do not
544 | excuse you from the conditions of this License.  If you cannot convey a
545 | covered work so as to satisfy simultaneously your obligations under this
546 | License and any other pertinent obligations, then as a consequence you may
547 | not convey it at all.  For example, if you agree to terms that obligate you
548 | to collect a royalty for further conveying from those to whom you convey
549 | the Program, the only way you could satisfy both those terms and this
550 | License would be to refrain entirely from conveying the Program.
551 | 
552 |   13. Use with the GNU Affero General Public License.
553 | 
554 |   Notwithstanding any other provision of this License, you have
555 | permission to link or combine any covered work with a work licensed
556 | under version 3 of the GNU Affero General Public License into a single
557 | combined work, and to convey the resulting work.  The terms of this
558 | License will continue to apply to the part which is the covered work,
559 | but the special requirements of the GNU Affero General Public License,
560 | section 13, concerning interaction through a network will apply to the
561 | combination as such.
562 | 
563 |   14. Revised Versions of this License.
564 | 
565 |   The Free Software Foundation may publish revised and/or new versions of
566 | the GNU General Public License from time to time.  Such new versions will
567 | be similar in spirit to the present version, but may differ in detail to
568 | address new problems or concerns.
569 | 
570 |   Each version is given a distinguishing version number.  If the
571 | Program specifies that a certain numbered version of the GNU General
572 | Public License "or any later version" applies to it, you have the
573 | option of following the terms and conditions either of that numbered
574 | version or of any later version published by the Free Software
575 | Foundation.  If the Program does not specify a version number of the
576 | GNU General Public License, you may choose any version ever published
577 | by the Free Software Foundation.
578 | 
579 |   If the Program specifies that a proxy can decide which future
580 | versions of the GNU General Public License can be used, that proxy's
581 | public statement of acceptance of a version permanently authorizes you
582 | to choose that version for the Program.
583 | 
584 |   Later license versions may give you additional or different
585 | permissions.  However, no additional obligations are imposed on any
586 | author or copyright holder as a result of your choosing to follow a
587 | later version.
588 | 
589 |   15. Disclaimer of Warranty.
590 | 
591 |   THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
592 | APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
596 | PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
597 | IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
599 | 
600 |   16. Limitation of Liability.
601 | 
602 |   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
610 | SUCH DAMAGES.
611 | 
612 |   17. Interpretation of Sections 15 and 16.
613 | 
614 |   If the disclaimer of warranty and limitation of liability provided
615 | above cannot be given local legal effect according to their terms,
616 | reviewing courts shall apply local law that most closely approximates
617 | an absolute waiver of all civil liability in connection with the
618 | Program, unless a warranty or assumption of liability accompanies a
619 | copy of the Program in return for a fee.
620 | 
621 |                      END OF TERMS AND CONDITIONS
622 | 
623 |             How to Apply These Terms to Your New Programs
624 | 
625 |   If you develop a new program, and you want it to be of the greatest
626 | possible use to the public, the best way to achieve this is to make it
627 | free software which everyone can redistribute and change under these terms.
628 | 
629 |   To do so, attach the following notices to the program.  It is safest
630 | to attach them to the start of each source file to most effectively
631 | state the exclusion of warranty; and each file should have at least
632 | the "copyright" line and a pointer to where the full notice is found.
633 | 
634 |     <one line to give the program's name and a brief idea of what it does.>
635 |     Copyright (C) <year>  <name of author>
636 | 
637 |     This program is free software: you can redistribute it and/or modify
638 |     it under the terms of the GNU General Public License as published by
639 |     the Free Software Foundation, either version 3 of the License, or
640 |     (at your option) any later version.
641 | 
642 |     This program is distributed in the hope that it will be useful,
643 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
644 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
645 |     GNU General Public License for more details.
646 | 
647 |     You should have received a copy of the GNU General Public License
648 |     along with this program.  If not, see <https://www.gnu.org/licenses/>.
649 | 
650 | Also add information on how to contact you by electronic and paper mail.
651 | 
652 |   If the program does terminal interaction, make it output a short
653 | notice like this when it starts in an interactive mode:
654 | 
655 |     <program>  Copyright (C) <year>  <name of author>
656 |     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
657 |     This is free software, and you are welcome to redistribute it
658 |     under certain conditions; type `show c' for details.
659 | 
660 | The hypothetical commands `show w' and `show c' should show the appropriate
661 | parts of the General Public License.  Of course, your program's commands
662 | might be different; for a GUI interface, you would use an "about box".
663 | 
664 |   You should also get your employer (if you work as a programmer) or school,
665 | if any, to sign a "copyright disclaimer" for the program, if necessary.
666 | For more information on this, and how to apply and follow the GNU GPL, see
667 | <https://www.gnu.org/licenses/>.
668 | 
669 |   The GNU General Public License does not permit incorporating your program
670 | into proprietary programs.  If your program is a subroutine library, you
671 | may consider it more useful to permit linking proprietary applications with
672 | the library.  If this is what you want to do, use the GNU Lesser General
673 | Public License instead of this License.  But first, please read
674 | <https://www.gnu.org/licenses/why-not-lgpl.html>.
675 | 


--------------------------------------------------------------------------------