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
  - organization
scopes: []
inputs:

  plugin_music:
    description: Enable music plugin
    type: boolean
    default: no

  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` (provider will be auto-detected from `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: ""

  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` is specifed, 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/--------/--------

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

  plugin_music_played_at:
    description: Recently played - Toggle last played timestamp display
    type: boolean
    default: no

  plugin_music_time_range:
    description: |
      Top tracks - Time range for `top` mode
      - `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

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