sudacode/metrics
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

doc(plugins/music): update

Browse Source
This commit is contained in:
lowlighter
2022-01-16 08:50:11 -05:00
parent 950b063fa1
commit 5855682e47
2 changed files with 278 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

458
source/plugins/music/README.md
View File

@@ -1,125 +1,182 @@
### 🎼 Music plugin
The *music* plugin lets you display :
<!--header-->
<table>
<td align="center">
<details open><summary>Random tracks from a playlist</summary>
<img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.music.playlist.svg">
</details>
<details open><summary>Recently listened</summary>
<img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.music.recent.svg">
</details>
<img width="900" height="1" alt="">
</td>
<tr><th colspan="2"><h3>🎼 Music plugin</h3></th></tr>
<tr><td colspan="2" align="center"><p>This plugin can display top and recently listened music tracks or from a random playlist.</p>
<p>Different music providers are supported.</p>
</td></tr>
<tr>
<th rowspan="3">Supported features<br><sub><a href="metadata.yml">→ Full specification</a></sub></th>
<td><a href="/source/templates/classic"><code>📗 Classic template</code></a></td>
</tr>
<tr>
<td><code>👤 Users</code> <code>👥 Organizations</code></td>
</tr>
<tr>
<td><code>🗝️ plugin_music_token</code></td>
</tr>
<tr>
<td colspan="2" align="center">
<details open><summary>Random tracks from a playlist</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.music.playlist.svg" alt=""></img></details>
<details open><summary>Recently listened</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.music.recent.svg" alt=""></img></details>
<img width="900" height="1" alt="">
</td>
</tr>
</table>
<!--/header-->
It can work in the following modes:
#### ➡️ Available options
### Playlist mode
<!--options-->
<table>
<tr>
<td align="center" nowrap="nowrap">Type</i></td><td align="center" nowrap="nowrap">Description</td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music</code></td>
<td rowspan="2"><p>Enable music plugin</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>boolean</code>
<br>
<b>default:</b> no<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_provider</code></td>
<td rowspan="2"><p>Music provider</p>
<ul>
<li><code>apple</code>: Apple Music</li>
<li><code>spotify</code>: Spotify</li>
<li><code>lastfm</code>: Last.fm</li>
<li><code>youtube</code>: YouTube Music</li>
</ul>
<p>This setting is optional when using <code>plugin_music_mode: playlist</code> (provider will be auto-detected from <code>plugin_music_playlist</code> URL)</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>allowed values:</b><ul><li>apple</li><li>spotify</li><li>lastfm</li><li>youtube</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_token</code></td>
<td rowspan="2"><p>Music provider token</p>
<p>Below is the expected token format for each provider:</p>
<ul>
<li><code>apple</code>: <em>(not supported)</em></li>
<li><code>spotify</code>: &quot;client_id, client_secret, refresh_token&quot;</li>
<li><code>lastfm</code>: &quot;api_key&quot;</li>
<li><code>youtube</code>: &quot;cookie&quot;</li>
</ul>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap">🔐 Token<br>
<b>type:</b> <code>token</code>
<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_mode</code></td>
<td rowspan="2"><p>Display mode</p>
<ul>
<li><code>playlist</code>: display random tracks from an URL playlist</li>
<li><code>recent</code>: display recently listened tracks</li>
<li><code>top</code>: display top listened artists/tracks</li>
</ul>
<p>If <code>plugin_music_playlist</code> is specifed, the default value is <code>playlist</code>, else it is <code>recent</code></p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>allowed values:</b><ul><li>playlist</li><li>recent</li><li>top</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_playlist</code></td>
<td rowspan="2"><p>Playlist URL</p>
<p>It must be from an &quot;embed url&quot; (i.e. music player iframes that can be integrated in other websites)</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_limit</code></td>
<td rowspan="2"><p>Display limit</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>number</code>
<i>(1 ≤
𝑥
≤ 100)</i>
<br>
<b>default:</b> 4<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_played_at</code></td>
<td rowspan="2"><p>Recently played - Toggle last played timestamp display</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>boolean</code>
<br>
<b>default:</b> no<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_time_range</code></td>
<td rowspan="2"><p>Top tracks - Time range for <code>top</code> mode</p>
<ul>
<li><code>short</code>: 4 weeks</li>
<li><code>medium</code>: 6 months</li>
<li><code>long</code>: several years</li>
</ul>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>default:</b> short<br>
<b>allowed values:</b><ul><li>short</li><li>medium</li><li>long</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_top_type</code></td>
<td rowspan="2"><p>Top tracks - Display type</p>
<ul>
<li><code>tracks</code>: display track</li>
<li><code>artists</code>: display artists</li>
</ul>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>default:</b> tracks<br>
<b>allowed values:</b><ul><li>tracks</li><li>artists</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_user</code></td>
<td rowspan="2"><p>Music provider username</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>default:</b> <code>→ User login</code><br></td>
</tr>
</table>
<!--/options-->
Select randomly a few tracks from a given playlist to share your favorites tracks with your visitors.
Select a music provider below for instructions.
<details>
<summary>Apple Music</summary>
Extract the *embed* URL of the playlist you want to share.
To do so, connect to [music.apple.com](https://music.apple.com/) and select the playlist you want to share.
From `...` menu, select `Share` and `Copy embed code`.
![Copy embed code of playlist](/.github/readme/imgs/plugin_music_playlist_apple.png)
Extract the source link from the code pasted in your clipboard:
```html
<iframe allow="" frameborder="" height="" style="" sandbox="" src="https://embed.music.apple.com/**/playlist/********"></iframe>
```
And use this value in `plugin_music_playlist` option.
</details>
<details>
<summary>Spotify</summary>
Extract the *embed* URL of the playlist you want to share.
To do so, Open Spotify and select the playlist you want to share.
From `...` menu, select `Share` and `Copy embed code`.
![Copy embed code of playlist](/.github/readme/imgs/plugin_music_playlist_spotify.png)
Extract the source link from the code pasted in your clipboard:
```html
<iframe src="https://open.spotify.com/embed/playlist/********" width="" height="" frameborder="0" allowtransparency="" allow=""></iframe>
```
And use this value in `plugin_music_playlist` option.
</details>
<details>
<summary>Last.fm</summary>
This mode is not supported for now.
</details>
<details>
<summary>YouTube Music</summary>
Extract the *playlist* URL of the playlist you want to share.
To do so, Open YouTube Music and select the playlist you want to share.
Extract the source link from copying it from the address bar:
```
https://music.youtube.com/playlist?list=********
```
And use this value in `plugin_music_playlist` option.
</details>
#### ℹ️ Examples workflows
[➡️ Available options for this plugin](metadata.yml)
```yaml
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_music: yes
plugin_music_limit: 4 # Limit to 4 entries
plugin_music_playlist: https://******** # Use extracted playlist link
# plugin_music_provider: (will be guessed through plugin_music_playlist)
# plugin_music_mode: (will be set to "playlist" when plugin_music_playlist is provided)
```
### Recently played & top modes
- **Recently played**: Display tracks you have played recently.
- **Top**: Display your top artists/tracks for a certain time period.
## 🎺 Configuring music provider
Select a music provider below for additional instructions.
<details>
<summary>Apple Music</summary>
## 🎙️ Spotify
This mode is not supported for now.
### 🗝️ Obtaining a token
I tried to find a way with *smart playlists*, *shortcuts* and other stuff but could not figure a workaround to do it without paying the $99 fee for the developer program.
So unfortunately this isn't available for now.
</details>
<details>
<summary>Spotify</summary>
Spotify does not have *personal tokens*, so it makes the process a bit longer because you're required to follow the [authorization workflow](https://developer.spotify.com/documentation/general/guides/authorization-guide/)... Follow the instructions below for a *TL;DR* to obtain a `refresh_token`.
Spotify does not have *personal tokens*, so it makes the process a bit longer because it is required to follow the [authorization workflow](https://developer.spotify.com/documentation/general/guides/authorization-guide/)... Follow the instructions below for a *TL;DR* to obtain a `refresh_token`.
Sign in to the [developer dashboard](https://developer.spotify.com/dashboard/) and create a new app.
Keep your `client_id` and `client_secret` and let this tab open for now.
@@ -134,7 +191,7 @@ Forge the authorization url with your `client_id` and the encoded `redirect_uri`
https://accounts.spotify.com/authorize?client_id=********&response_type=code&scope=user-read-recently-played%20user-top-read&redirect_uri=https%3A%2F%2Flocalhost
```
When prompted, authorize your application.
When prompted, authorize application.
![Authorize application](/.github/readme/imgs/plugin_music_recent_spotify_token_1.png)
@@ -142,7 +199,7 @@ Once redirected to `redirect_uri`, extract the generated authorization `code` fr
![Extract authorization code from url](/.github/readme/imgs/plugin_music_recent_spotify_token_2.png)
Go back to your developer dashboard tab, and open the web console of your browser to paste the following JavaScript code, with your own `client_id`, `client_secret`, authorization `code` and `redirect_uri`.
Go back to developer dashboard tab, and open the web console of your browser to paste the following JavaScript code, with your own `client_id`, `client_secret`, authorization `code` and `redirect_uri`.
```js
(async () => {
@@ -173,25 +230,43 @@ It should return a JSON response with the following content:
Register your `client_id`, `client_secret` and `refresh_token` in secrets to finish setup.
</details>
### 🔗 Get an embed playlist url for `plugin_music_playlist`
<details>
<summary>Last.fm</summary>
Connect to [spotify.com](https://www.spotify.com) and select the playlist you want to share.
From `...` menu, select `Share` and `Copy embed code`.
Obtain a Last.fm API key.
![Copy embed code of playlist](/.github/readme/imgs/plugin_music_playlist_spotify.png)
To do so, you can simply [create an API account](https://www.last.fm/api/account/create) or [use an existing one](https://www.last.fm/api/accounts).
Extract the source link from the code pasted in your clipboard:
```html
<iframe src="https://open.spotify.com/embed/playlist/********" width="" height="" frameborder="0" allowtransparency="" allow=""></iframe>
```
Register your API key to finish setup.
## 🍎 Apple Music
</details>
### 🗝️ Obtaining a token
<details>
<summary>YouTube Music</summary>
*(Not available)*
Extract your YouTube Music cookies.
> 😥 Unfortunately I wasn't able to find a workaround to avoid paying the $99 fee for the developer program, even using workarounds like *smart playlists*, *shortcuts* and other stuff. However if you really want this feature, you could [sponsor me](github.com/sponsors/lowlighter) and I could eventually invest in a developper account with enough money, implement it and also eventually offer service on the shared instance
To do so, open [YouTube Music](https://music.youtube.com) (whilst logged in) on any modern browser
### 🔗 Get an embed playlist url for `plugin_music_playlist`
Connect to [music.apple.com](https://music.apple.com/) and select the playlist you want to share.
From `...` menu, select `Share` and `Copy embed code`.
![Copy embed code of playlist](/.github/readme/imgs/plugin_music_playlist_apple.png)
Extract the source link from the code pasted in your clipboard:
```html
<iframe allow="" frameborder="" height="" style="" sandbox="" src="https://embed.music.apple.com/**/playlist/********"></iframe>
```
## ⏯️ Youtube Music
### 🗝️ Obtaining a token
Login to [YouTube Music](https://music.youtube.com) on any modern browser.
Open the developer tools (Ctrl-Shift-I) and select the “Network” tab
@@ -203,125 +278,28 @@ Click on the Name of any matching request. In the “Headers” tab, scroll to t
![Copy cookie value](/.github/readme/imgs/plugin_music_recent_youtube_cookie_2.png)
</details>
### 🔗 Get an embed playlist url for `plugin_music_playlist`
#### ➡️ Available options
Extract the *playlist* URL of the playlist you want to share.
<!--options-->
<table>
<tr>
<td align="center" nowrap="nowrap">Type</i></td><td align="center" nowrap="nowrap">Description</td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music</code></td>
<td rowspan="2"><p>Display your music tracks</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>boolean</code>
<br>
<b>default:</b> no<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_provider</code></td>
<td rowspan="2"><p>Music provider</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>allowed values:</b><ul><li>apple</li><li>spotify</li><li>lastfm</li><li>youtube</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_token</code></td>
<td rowspan="2"><p>Music provider personal token</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap">🔐 Token<br>
<b>type:</b> <code>token</code>
<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_mode</code></td>
<td rowspan="2"><p>Plugin mode</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>allowed values:</b><ul><li>playlist</li><li>recent</li><li>top</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_playlist</code></td>
<td rowspan="2"><p>Embed playlist url</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_limit</code></td>
<td rowspan="2"><p>Maximum number of tracks to display</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>number</code>
<i>(1 ≤
𝑥
≤ 100)</i>
<br>
<b>default:</b> 4<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_played_at</code></td>
<td rowspan="2"><p>Display when the track was played</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>boolean</code>
<br>
<b>default:</b> no<br></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_time_range</code></td>
<td rowspan="2"><p>Time period for top mode</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>default:</b> short<br>
<b>allowed values:</b><ul><li>short</li><li>medium</li><li>long</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_top_type</code></td>
<td rowspan="2"><p>Whether to show tracks or artists in top mode</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>default:</b> tracks<br>
<b>allowed values:</b><ul><li>tracks</li><li>artists</li></ul></td>
</tr>
<tr>
<td nowrap="nowrap"><code>plugin_music_user</code></td>
<td rowspan="2"><p>Music provider username</p>
<img width="900" height="1" alt=""></td>
</tr>
<tr>
<td nowrap="nowrap"><b>type:</b> <code>string</code>
<br>
<b>default:</b> <code>→ User login</code><br></td>
</tr>
</table>
<!--/options-->
Connect to [music.youtube.com](https://music.youtube.com) and select the playlist you want to share.
*[→ Full specification](metadata.yml)*
Extract the source link from the code pasted in your clipboard:
```
https://music.youtube.com/playlist?list=********
```
#### ℹ️ Examples workflows
## 📻 Last.fm
### 🗝️ Obtaining a token
[Create an API account](https://www.last.fm/api/account/create) or [use an existing one](https://www.last.fm/api/accounts) to obtain a Last.fm API key.
### 🔗 Get an embed playlist url for `plugin_music_playlist`
*(Not available)*
## ℹ️ Examples workflows
<!--examples-->
```yaml

100
source/plugins/music/metadata.yml
View File

@@ -1,5 +1,12 @@
name: "🎼 Music plugin"
category: social
description: |
This plugin can display top and recently listened music tracks or from a random playlist.
Different music providers are supported.
examples:
+random tracks from a playlist: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.music.playlist.svg
+recently listened: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.music.recent.svg
index: 2
supports:
- user
@@ -7,87 +14,100 @@ supports:
scopes: []
inputs:
# Enable or disable plugin
plugin_music:
description: Display your music tracks
description: Enable music plugin
type: boolean
default: no
# Name of music provider
# This is optional for "playlist" mode (it can be deduced automatically from "plugin_music_playlist" url)
# This is required in other modes
plugin_music_provider:
description: Music provider
description: |
Music provider
- `apple`: Apple Music
- `spotify`: Spotify
- `lastfm`: Last.fm
- `youtube`: YouTube Music
This setting is optional when using `plugin_music_mode: playlist` (provider will be auto-detected from `plugin_music_playlist` URL)
type: string
default: ""
values:
- apple # Apple Music
- spotify # Spotify
- lastfm # Last.fm
- youtube # YouTube
- apple
- spotify
- lastfm
- youtube
# Music provider token
# This may be required depending on music provider used and plugin mode
# - "apple" : not required
# - "spotify" : required for "recent" or "top" mode, format is "client_id, client_secret, refresh_token"
# - "lastfm" : required, format is "api_key"
# - "youtube" : required for "recent" mode, format is "cookie"
plugin_music_token:
description: Music provider personal token
description: |
Music provider token
Below is the expected token format for each provider:
- `apple`: *(not supported)*
- `spotify`: "client_id, client_secret, refresh_token"
- `lastfm`: "api_key"
- `youtube`: "cookie"
type: token
default: ""
# Plugin mode
plugin_music_mode:
description: Plugin mode
type: string
default: "" # Defaults to "recent" or to "playlist" if "plugin_music_playlist" is specified
values:
- playlist # Display tracks from an embed playlist randomly
- recent # Display recently listened tracks
- top # Display top listened artists/tracks
description: |
Display mode
- `playlist`: display random tracks from an URL playlist
- `recent`: display recently listened tracks
- `top`: display top listened artists/tracks
If `plugin_music_playlist` is specifed, the default value is `playlist`, else it is `recent`
type: string
default: ""
values:
- playlist
- recent
- top
# Embed playlist url (i.e. url used by music player iframes)
plugin_music_playlist:
description: Embed playlist url
description: |
Playlist URL
It must be from an "embed url" (i.e. music player iframes that can be integrated in other websites)
type: string
default: ""
example: https://embed.music.apple.com/--/playlist/--------/--------
# Number of music tracks to display
plugin_music_limit:
description: Maximum number of tracks to display
description: Display limit
type: number
default: 4
min: 1
max: 100
# Display when track was last played
plugin_music_played_at:
description: Display when the track was played
description: Recently played - Toggle last played timestamp display
type: boolean
default: no
# Time range for "top" mode
plugin_music_time_range:
description: Time period for top mode
description: |
Top tracks - Time range for `top` mode
- `short`: 4 weeks
- `medium`: 6 months
- `long`: several years
type: string
default: short # Defaults to "short" (4 weeks)
default: short
values:
- short # Top artists/tracks from past 4 weeks
- medium # Top artists/tracks from past 6 months
- long # Top artists/tracks from several years
- short
- medium
- long
# Option for "top" mode to select tracks or artists
plugin_music_top_type:
description: Whether to show tracks or artists in top mode
description: |
Top tracks - Display type
- `tracks`: display track
- `artists`: display artists
type: string
default: tracks
values:
- tracks
- artists
# Username on music provider service
plugin_music_user:
description: Music provider username
type: string