Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wsmd/github-now-playing
🎵 Display what you're listening to right on your Github profile
https://github.com/wsmd/github-now-playing
github github-profile itunes lastfm macos music now-playing spotify
Last synced: 3 months ago
JSON representation
🎵 Display what you're listening to right on your Github profile
- Host: GitHub
- URL: https://github.com/wsmd/github-now-playing
- Owner: wsmd
- License: mit
- Created: 2019-04-07T23:50:45.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T12:24:32.000Z (about 2 years ago)
- Last Synced: 2024-10-26T14:25:00.393Z (3 months ago)
- Topics: github, github-profile, itunes, lastfm, macos, music, now-playing, spotify
- Language: TypeScript
- Homepage:
- Size: 1.3 MB
- Stars: 79
- Watchers: 3
- Forks: 4
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
github-now-playing
📖 Table of Contents
- [Motivation](#motivation)
- [Installation](#installation)
- [Example](#example)
- [API](#api)
- [Class: `GitHubNowPlaying`](#class-githubnowplaying)
- [Constructor Options](#constructor-options)
- [Methods](#methods)
- [`nowPlaying.setSource(source)`](#nowplayingsetsourcesource)
- [`nowPlaying.on(event, listener)`](#nowplayingonevent-listener)
- [`nowPlaying.off(event, listener)`](#nowplayingoffevent-listener)
- [`nowPlaying.listen()`](#nowplayinglisten)
- [`nowPlaying.stop()`](#nowplayingstop)
- [Sources Providers: `GitHubNowPlaying.Sources`](#sources-providers-githubnowplayingsources)
- [`LastFM`](#lastfm)
- [`ITunes`](#itunes)
- [`Spotify`](#spotify)
- [Events: `GitHubNowPlaying.Events`](#events-githubnowplayingevents)
- [`Error`](#error)
- [`ListenStart`](#listenstart)
- [`ListenStop`](#listenstop)
- [`StatusUpdated`](#statusupdated)
- [`StatusCleared`](#statuscleared)
## Motivation
GitHub introduced a [new feature](https://github.blog/changelog/2019-01-09-set-your-status/) that allows you to set a status on your profile, so I thought it would be a cool idea if I could share the music I'm listening to — kind of like #NowPlaying — right on my GitHub profile!
## Installation
This library is available on the [npm](https://www.npmjs.com/package/github-now-playing) registry as a [node](https://nodejs.org/en/) module and can be installed by running:
```sh
# via npm
npm install --save github-now-playing
# via yarn
yarn add github-now-playing
```
You also need to generate a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with the **user** scope to allow this library to communicate with GitHub.
## Example
```ts
import { GitHubNowPlaying } from 'github-now-playing';
const nowPlaying = new GitHubNowPlaying({
token: process.env.GITHUB_ACCESS_TOKEN,
});
// Create a new source to retrieve the track that is currently playing
const spotifySource = new GitHubNowPlaying.Sources.Spotify({
// wait time in milliseconds between checks for any track changes
updateFrequency: 1000,
});
// Make sure a source is set before calling listen()
nowPlaying.setSource(spotifySource);
// Don't forget to handle the error event!
nowPlaying.on(GitHubNowPlaying.Events.Error, error => {
console.log('something went wrong');
});
// Listen to any track changes and update the profile status accordingly.
nowPlaying.listen();
// Don't forget to stop reporting any track changes when the process exists.
process.on('SIGINT', () => {
// Calling the stop() method will clear the profile status.
nowPlaying.stop()
});
```
## API
`github-now-playing` exposes a named export class `GitHubNowPlaying` that is also a namespace for various [source providers](#sources-providers-githubnowplayingsources) and [event names](#events-githubnowplayingevents).
### Class: `GitHubNowPlaying`
```ts
new GitHubNowPlaying(options: GitHubNowPlayingConstructorOptions)
```
Creates a new instance of `GitHubNowPlaying`.
#### Constructor Options
An object with the following keys:
- `token: string`: a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with the **user** scope.
#### Methods
##### `nowPlaying.setSource(source)`
Assigns a [source provider object](#sources) from which the currently-playing track will be retrieved.
This method must be called before calling [`listen()`](#listen-void).
##### `nowPlaying.on(event, listener)`
Adds the `listener` function as an event handler for the named `event`. The `event` parameter can be one of the values available under the [`GitHubNowPlaying.Events` namespace](#events).
Returns a reference to the `GitHubNowPlaying` instance, so that calls can be chained.
##### `nowPlaying.off(event, listener)`
Removes the specified `listener` function for the named `event`.
The `event` parameter can be one of the values available under the [`GitHubNowPlaying.Events` namespace](#events).
Returns a reference to the `GitHubNowPlaying` instance, so that calls can be chained.
##### `nowPlaying.listen()`
Starts listening to any track changes coming from the specified source and updates the GitHub profile status accordingly.
The event `GitHubNowPlaying.Events.ListenStart` is emitted upon calling this method.
Additionally, every time the profile status is updated, the event `GitHubNowPlaying.Events.StatusUpdated` is emitted with the [profile status](https://github.com/wsmd/github-profile-status#userstatus) object.
Note that upon calling `listen()`, the profile status will be updated immediately to reflect the currently playing track.
##### `nowPlaying.stop()`
Stops listening to any track changes.
Calling this method will result in clearing the profile status if it has been already updated with a currently playing track.
If the status is cleared, the event `GitHubNowPlaying.Events.StatusCleared` is emitted, then followed by the event `GitHubNowPlaying.Events.ListenStop`.
This method is asynchronous and will resolve after clearing the profile status.
----
### Sources Providers: `GitHubNowPlaying.Sources`
`GitHubNowPlaying` relies on a source provider object that retrieves the currently playing track from a specific source.
These sources can be either local desktop applications, such [iTunes](https://www.apple.com/itunes/) or [Spotify](https://www.spotify.com/us/), or even via web APIs, such as Last.fm.
`GitHubNowPlaying` comes with built-in support for all of these sources. Note that support for desktop applications is currently limited to macOS.
The following sources are available under the namespace `GitHubNowPlaying.Sources`:
#### `LastFM`
Fetches information about the currently-playing track via Last.fm.
```js
const lastFmSource = new GitHubNowPlaying.Sources.LastFM({
apiKey: process.env.LAST_FM_API_KEY, // Your Last.fm API key
updateFrequency: 1000,
});
nowPlaying.setSource(lastFmSource);
```
#### `ITunes`
Fetches information about the currently-playing track in [iTunes](https://www.apple.com/itunes/).
```js
const iTunesSource = new GitHubNowPlaying.Sources.ITunes({
updateFrequency: 1000,
});
nowPlaying.setSource(iTunesSource);
```
Platforms supported: macOS
#### `Spotify`
Fetches information about the currently-playing track in Spotify.
```js
const spotifySource = new GitHubNowPlaying.Sources.Spotify({
updateFrequency: 1000,
});
nowPlaying.setSource(spotifySource);
```
Platforms supported: macOS
---
### Events: `GitHubNowPlaying.Events`
Instances of `GitHubNowPlaying` emit various events during the program life-cycle. You can add or remove event listeners via [`on()`](#nowplayingonevent-listener) and [`off()`](#nowplayingoffevent-listener) respectively.
#### `Error`
Emitted when an error occurs:
```ts
nowPlaying.on(GitHubNowPlaying.Events.Error, (error) => { /* ... */ });
```
#### `ListenStart`
Emitted when `GitHubNowPlaying` starts listening to track changes via the specified source:
```ts
nowPlaying.on(GitHubNowPlaying.Events.ListenStart, () => { /* ... */ });
```
#### `ListenStop`
Emitted when `GitHubNowPlaying` has stopped listening to track changes via the specified source:
```ts
nowPlaying.on(GitHubNowPlaying.Events.ListenStop, () => { /* ... */ });
```
#### `StatusUpdated`
Emitted when `GitHubNowPlaying` has updated the profile status with currently-playing track successfully. Listeners of this event are called with the [user-status object](https://github.com/wsmd/github-profile-status#userstatus).
```ts
nowPlaying.on(GitHubNowPlaying.Events.ListenStop, (status) => { /* ... */ });
```
#### `StatusCleared`
Emitted when `GitHubNowPlaying` has cleared the profile status after it has been updated with a currently playing track. This happens when the source provider reports that there are no tracks are currently playing, or when [`stop()`](#nowplayingstop) is called.
```ts
nowPlaying.on(GitHubNowPlaying.Events.StatusCleared, () => { /* ... */ });
```
# See Also
- [`github-profile-status`](https://github.com/wsmd/github-profile-status)
# License
MIT