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