npm package: @macrowave/player
Description: Embeddable live streaming player for Macrowave - A lightweight web component for embedding live audio/video streams
Author: Macrowave
Latest version: 1.0.9

# @macrowave/player

Embeddable live streaming player for [Macrowave](https://macrowave.co) - A lightweight web component for embedding live audio/video streams on any website.

## Installation

### Via CDN (Recommended)

The easiest way to use the Macrowave player is via CDN:

```html
<!-- Using jsDelivr (Recommended) -->
<script src="https://cdn.jsdelivr.net/npm/@macrowave/player"></script>
<macrowave-player station="username/station-slug"></macrowave-player>
```

**Alternative CDNs:**

```html
<!-- Using unpkg -->
<script src="https://unpkg.com/@macrowave/player"></script>
<macrowave-player station="username/station-slug"></macrowave-player>

<!-- Using esm.sh -->
<script src="https://esm.sh/@macrowave/player"></script>
<macrowave-player station="username/station-slug"></macrowave-player>
```

### Via npm

If you're using a bundler, you can install via npm:

```bash
npm install @macrowave/player
```

Then import in your JavaScript:

```javascript
import '@macrowave/player';
```

## Usage

### Basic Example

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Stream</title>
</head>
<body>
  <h1>Listen Live</h1>

  <!-- Load the player script -->
  <script src="https://cdn.jsdelivr.net/npm/@macrowave/player"></script>

  <!-- Add the player element -->
  <macrowave-player station="username/station-slug"></macrowave-player>
</body>
</html>
```

### Configuration Options

The player supports several attributes:

```html
<macrowave-player
  station="username/station-slug"
  theme="dark"
  autoplay="false"
></macrowave-player>
```

#### Attributes

- **`station`** (required): The station identifier in format `username/station-slug`
- **`theme`** (optional): Player theme - `"light"` or `"dark"` (default: `"dark"`)
- **`autoplay`** (optional): Auto-start playback - `"true"` or `"false"` (default: `"false"`)

### Styling

The player uses Shadow DOM for style encapsulation. You can control its container size with CSS:

```html
<style>
  macrowave-player {
    width: 100%;
    max-width: 800px;
    height: 600px;
    display: block;
    margin: 0 auto;
  }
</style>
```

### Responsive Design

```html
<style>
  macrowave-player {
    width: 100%;
    height: 400px;
  }

  @media (min-width: 768px) {
    macrowave-player {
      height: 600px;
    }
  }
</style>
```

## Programmatic Control

You can control the player via JavaScript:

```html
<macrowave-player id="my-player" station="username/station-slug"></macrowave-player>

<script>
  const player = document.getElementById('my-player');

  // Change station dynamically
  player.setAttribute('station', 'other-user/other-station');

  // Change theme
  player.setAttribute('theme', 'light');

  // Enable autoplay
  player.setAttribute('autoplay', 'true');
</script>
```

## Version Pinning

For production use, we recommend pinning to a specific version:

```html
<!-- Pin to specific version -->
<script src="https://cdn.jsdelivr.net/npm/@macrowave/player@1.0.0"></script>

<!-- Or use semver range (auto-updates patch versions) -->
<script src="https://cdn.jsdelivr.net/npm/@macrowave/player@1"></script>
```

## Browser Support

The player works on all modern browsers:
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

**Note:** Internet Explorer is not supported.

## Performance

- Single JavaScript file (~590KB, ~163KB gzipped)
- Lazy loads when visible
- Efficient WebRTC streaming via LiveKit
- No external dependencies

## Security

- Uses Shadow DOM to prevent style/script conflicts
- All communication over HTTPS
- No access to your site's cookies or data

## Platform Support

The player works on popular platforms including:
- WordPress
- Wix
- Squarespace
- Webflow
- Any HTML-based website

For detailed integration guides, see the [full documentation](https://macrowave.co/docs/embed).

## License

MIT

## Support

- Website: [macrowave.co](https://macrowave.co)
- Issues: [GitHub Issues](https://github.com/macrowave/app/issues)
- Email: support@macrowave.co

## Contributing

This package is part of the Macrowave monorepo. For contributing guidelines, see the [main repository](https://github.com/macrowave/app).