ng-media-player

A lightweight Angular media player with audio, video, queue, crossfade, lyrics, and RTL support — built with Angular Signals, no extra dependencies.

🔴 Live Demo

Installation

npm install ngx-pro-media-player @angular/cdk

Usage

Import the component:

import { NgxMediaPlayer } from 'ngx-pro-media-player';

@Component({
  imports: [NgxMediaPlayer],
})
export class AppComponent {}

Add to your template:

<ngx-media-player [mediaList]="tracks" language="en" direction="ltr" />

Pass a single track as a one-item array:

<ngx-media-player [mediaList]="[track]" language="en" direction="ltr" />

Inputs

| Input | Type | Default | Description | |---|---|---|---| | mediaList | MediaItem[] | [] | List of tracks / single track | | language | 'en' \| 'fa' | 'fa' | UI language | | direction | 'ltr' \| 'rtl' | 'rtl' | Text direction | | crossfadeSeconds | number | 2.5 | Crossfade duration between tracks (seconds) | | allowDownload | boolean | false | Show a download button that lets the user download the currently playing media file directly from its URL |

Outputs

| Output | Payload | Description | |---|---|---| | closed | void | Emitted when the user closes the player (close button). Playback is paused automatically; the consumer is responsible for clearing mediaList if the player should disappear. | | liked | MediaItem | Emitted with the currently playing track when the user clicks the like button and item.liked is not true. The player does not call any API itself — handle the request (e.g. send it to your backend) in your own handler. | | unliked | MediaItem | Emitted instead of liked when the user clicks the like button while item.liked is true — i.e. the button acts as a toggle. | | addedToPlaylist | MediaItem | Emitted with the currently playing track when the user clicks the "add to playlist" button and item.inPlaylist is not true. The consumer decides what to do (e.g. call an API). | | removedFromPlaylist | MediaItem | Emitted instead of addedToPlaylist when the user clicks the button while item.inPlaylist is true — i.e. the button acts as a toggle. | | removedFromQueue | MediaItem | Emitted when the user clicks the ✕ on a queue item to remove it. The player removes the item from playback immediately; the consumer should remove it from mediaList too so it doesn't get re-added. |

<ngx-media-player
  [mediaList]="tracks"
  language="en"
  direction="ltr"
  (closed)="tracks = []"
  (liked)="onLike($event)"
  (unliked)="onUnlike($event)"
  (addedToPlaylist)="onAddToPlaylist($event)"
  (removedFromPlaylist)="onRemoveFromPlaylist($event)"
  (removedFromQueue)="onRemoveFromQueue($event)"
/>

onLike(track: MediaItem): void {
  this.http.post('/api/likes', { trackId: track.id }).subscribe(() => {
    track.liked = true;
  });
}

onUnlike(track: MediaItem): void {
  this.http.delete(`/api/likes/${track.id}`).subscribe(() => {
    track.liked = false;
  });
}

onAddToPlaylist(track: MediaItem): void {
  this.http.post('/api/playlists/current/items', { trackId: track.id }).subscribe(() => {
    track.inPlaylist = true;
  });
}

onRemoveFromPlaylist(track: MediaItem): void {
  this.http.delete(`/api/playlists/current/items/${track.id}`).subscribe(() => {
    track.inPlaylist = false;
  });
}

onRemoveFromQueue(track: MediaItem): void {
  this.tracks = this.tracks.filter(t => t.id !== track.id);
}

Note: the player hides itself automatically whenever mediaList is empty — there's no separate "visible" flag.

MediaItem

interface MediaItem {
  id: string;
  title: string;
  artist?: string;
  album?: string;
  cover?: string;
  poster?: string;       // video poster
  url: string;
  type: 'audio' | 'video';
  duration?: number;
  lyrics?: LyricLine[];
  liked?: boolean;        // mark as already liked — hides the liked action / shows it as active
  inPlaylist?: boolean;   // mark as already in playlist — hides the add action / shows it as active
}

interface LyricLine {
  time: number;          // seconds
  text: string;
}

Example

const tracks: MediaItem[] = [
  {
    id: '1',
    title: 'Track One',
    artist: 'Artist A',
    cover: 'https://example.com/cover.jpg',
    url: 'https://example.com/track1.mp3',
    type: 'audio',
  },
  {
    id: '2',
    title: 'My Video',
    url: 'https://example.com/video.mp4',
    poster: 'https://example.com/poster.jpg',
    type: 'video',
  },
];

Features

• 🎵 Audio & 🎬 Video playback
• 🔀 Shuffle & 🔁 Repeat (off / all / one)
• ⏭ Queue with drag-and-drop reorder
• 🌊 Crossfade between tracks
• 📜 Lyrics panel
• 🌐 RTL & LTR support
• 📶 Buffer progress bar
• ⌨️ Media Session API (OS lock screen controls)

Support

If this project saved you some time, consider buying me a coffee ☕

Note for maintainers: projects/ngx-pro-media-player/README.md is the single source of truth. After editing it, copy it to the workspace root to keep GitHub in sync:

cp projects/ngx-pro-media-player/README.md README.md

The build (ng build ngx-pro-media-player) automatically copies it to dist/ for npm.