npm package: @outbook/webcomponents-player
Description: Web component media player (formerly mythical-player)
Author: Antonio Rodríguez
Latest version: 1.4.5

# @outbook/webcomponents-player

This package provides a web component for an audio player with playlist functionality.

## Installation

```bash
npm install @outbook/webcomponents-player
```

## Usage

### As a Lit Element

```javascript
import {html} from 'lit';
import {Player} from '@outbook/webcomponents-player';

const myPlaylist = [
  {
    file: 'path/to/your/audio1.mp3',
    title: 'Song Title 1',
    artist: 'Artist Name 1',
    album: 'Album Name 1',
    cover: {
      name: 'cover1.jpg', // or a URL
      // Other cover properties if available
    }
  },
  {
    file: 'path/to/your/audio2.mp3',
    title: 'Song Title 2',
    artist: 'Artist Name 2',
    album: 'Album Name 2',
    cover: {
      name: 'cover2.png', // or a URL
      // Other cover properties if available
    }
  }
];

function render() {
  return html`
    ${Player({
    playlist: myPlaylist,
    lang: 'en',
    showFileExtension: true,
    showArtwork: true,
    showTrackNumber: true,
    playlistAlign: 'right'
  })}
  `;
}
```

### Direct HTML Usage

You can also use the custom element directly in your HTML. Remember to import the component's JavaScript for the custom element to be defined.

```javascript
import '@outbook/webcomponents-player';
```

```html
<outbook-player
  lang="en"
  show-file-extension="true"
  show-artwork="true"
  show-track-number="true"
  playlist-align="right"
  .playlist='[
    {
      "file": "path/to/your/audio1.mp3",
      "title": "Song Title 1",
      "artist": "Artist Name 1",
      "album": "Album Name 1",
      "cover": {
        "name": "cover1.jpg"
      }
    },
    {
      "file": "path/to/your/audio2.mp3",
      "title": "Song Title 2",
      "artist": "Artist Name 2",
      "album": "Album Name 2",
      "cover": {
        "name": "cover2.png"
      }
    }
  ]'
></outbook-player>
```

**Note:** When using the `playlist` property directly in HTML, you must pass a JSON string. Ensure the JSON is valid and properly escaped if necessary.

## Component: `outbook-player`

This is the underlying web component. It can be used directly in HTML or in any framework.

### Properties

| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
| `lang` | `lang` | `String` | `'en'` | The language to use for localized strings. |
| `playlist` | `playlist` | `Array` | `[]` | An array of track objects, each with `file`, `title`, `artist`, `album`, and `cover` properties. |
| `extraClasses` | `extraClasses` | `String` | `undefined` | Classes to add to the host element. |
| `show-file-extension` | `showFileExtension` | `Boolean` | `true` | Whether to display file extensions in the playlist. |
| `show-artwork` | `showArtwork` | `Boolean` | `true` | Whether to display artwork in the playlist. |
| `show-track-number` | `showTrackNumber` | `Boolean` | `true` | Whether to display track numbers in the playlist. |
| `playlist-align` | `playlistAlign` | `String` | `'right'` | Aligns the playlist to 'left' or 'right' of the track info. |

### Styling

This component uses Shadow DOM, and its styles are self-contained. The component's styles are automatically applied and encapsulated, so there is no need to import any additional stylesheets.

### Custom Properties

Should not be used with css `light-dark` function.

| Custom Property                                       | Description                                   |
|-------------------------------------------------------|-----------------------------------------------|
| `--outbook-player--color-accent-0`                    | Accent color 0.                               |
| `--outbook-player--color-accent-50`                   | Accent color 50.                              |
| `--outbook-player--color-accent-100`                  | Accent color 100.                             |
| `--outbook-player--color-accent-200`                  | Accent color 200.                             |
| `--outbook-player--color-accent-300`                  | Accent color 300.                             |
| `--outbook-player--color-accent-400`                  | Accent color 400.                             |
| `--outbook-player--color-accent-500`                  | Accent color 500.                             |
| `--outbook-player--color-accent-600`                  | Accent color 600.                             |
| `--outbook-player--color-accent-700`                  | Accent color 700.                             |
| `--outbook-player--color-accent-800`                  | Accent color 800.                             |
| `--outbook-player--color-accent-900`                  | Accent color 900.                             |
| `--outbook-player--color-accent-950`                  | Accent color 950.                             |
| `--outbook-player--color-accent-1000`                 | Accent color 1000.                            |

## License

This component is licensed under the Apache-2.0 License.