name: 🎼 Music activity and suggestions
category: social
description: |
  This plugin can display top and recently listened music tracks or titles from a random playlist.

  Different music providers are supported.
disclaimer: |
  This plugin is not affiliated, associated, authorized, endorsed by, or in any way officially connected with any of the supported provider.
  All product and company names are trademarks™ or registered® trademarks of their respective holders.
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: 5
supports:
  - user
  - organization
scopes: []
inputs:

  plugin_music:
    description: |
      Enable music plugin
    type: boolean
    default: no
    extras:
      - metrics.run.puppeteer.scrapping

  plugin_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`](/source/plugins/music/README.md#plugin_music_mode) (provider will be auto-detected from [`plugin_music_playlist`](/source/plugins/music/README.md#plugin_music_playlist) URL)
    type: string
    default: ""
    values:
      - apple
      - spotify
      - lastfm
      - youtube

  plugin_music_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: ""
    extras:
      - metrics.api.music.any

  plugin_music_user:
    description: |
      Music provider username
    type: string
    default: .user.login
    preset: no

  plugin_music_mode:
    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`](/source/plugins/music/README.md#plugin_music_playlist) is specified, the default value is `playlist`, else it is `recent`
    type: string
    default: ""
    values:
      - playlist
      - recent
      - top

  plugin_music_playlist:
    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/--------/--------
    preset: no

  plugin_music_limit:
    description: |
      Display limit
    type: number
    default: 4
    min: 1
    max: 100

  plugin_music_played_at:
    description: |
      Recently played - Last played timestamp
    type: boolean
    default: no

  plugin_music_time_range:
    description: |
      Top tracks - Time range

      - `short`: 4 weeks
      - `medium`: 6 months
      - `long`: several years
    type: string
    default: short
    values:
      - short
      - medium
      - long

  plugin_music_top_type:
    description: |
      Top tracks - Display type

      - `tracks`: display track
      - `artists`: display artists
    type: string
    default: tracks
    values:
      - tracks
      - artists