Home

Awesome

ByteArk Player Container for Angular

NPM

Demo

You can try on the demo page.

Features

Installation

This library is distributed via NPM. You may install from NPM or Yarn.

# For NPM
npm install --save @byteark/byteark-player-angular
# For Yarn
yarn add @byteark/byteark-player-angular
# For pnpm
pnpm add @byteark/byteark-player-angular

Usage

To use the ByteArk Player Container in your Angular application, follow these steps:

  1. Import the ByteArkPlayerContainer component:

    import { Component } from "@angular/core";
    import { ByteArkPlayerContainer, type ByteArkPlayerContainerProps } from "@byteark/byteark-player-angular";
    
    @Component({
      selector: "app-sample-blog",
      standalone: true,
      imports: [ByteArkPlayerContainer],
      template: ` <byteark-player-container [options]="options"></byteark-player-container> `,
    })
    export class SampleBlogComponent {
      title = "ByteArk Player Container | Sample Blog";
    }
    
  2. Add the component to your template:

    <byteark-player-container [options]="options"></byteark-player-container>
    
  3. Configure the player options:

    export class SampleBlogComponent {
      title = "ByteArk Player Container | Sample Blog";
      options: ByteArkPlayerContainerProps = {
        fluid: true,
        autoplay: false,
        aspectRatio: "16:9",
        poster: "https://example.com/poster.jpg",
        sources: [
          {
            src: "https://example.com/video.mp4",
            type: "video/mp4",
            title: "Sample Video",
          },
        ],
      };
    }
    

Basic Props

Following properties are the properties that can be updated to the player, without re-creating the player instance. Additional properties will be passed to player.

NameTypeDefaultDescription
autoplayBoolean/StringtrueAutoplay the video after player is created. (true/false/'muted'/'play'/'any')
aspectRatioString-Use with fluid layout mode, to inform expected video's aspect ratio (16:9)
controlsBooleantrueShow/hide the controls bar.
fillBoolean-Use fill layout mode.
fluidBoolean-Use fluid layout mode.
loopBoolean-Restart the video playback after plays to the end.
mutedBoolean-Play the video without sounds.
playerSlugIdString-SlugId of player created via api player server service
playerVersionString1.0Version of the player to use.
playbackRateNumber1.0Playback speed. 1.0 means original speed.
playsinlineBooleantrueShould be true so custom controls available on all platforms, including iOS.
posterString-Image to be show before the video is playing.
preloadString-Preload the video before play. ('none'/'metadata'/'auto')
responsiveBoolean-Auto show/hide controls depending on the screen size.
seekButtonsBooleanfalseShow 10 seconds seek buttons and allow double-tap to seek on mobile.
sourcesArray-Array of video source object to be played.
volumeNumber-Video's volume, between 0 to 1.

You can also use other props not listed here, but appear as VideoJS's options. However, changing props will not effective after the player is created.

Source Object

The source object has 2 required fields, and more optional field:

NameTypeDescription
srcStringURL to the video.
typeStringVideo content type.
titleStringVideo title to display on the player.
videoIdStringVideo's ID, usually used on Analytics.
posterStringPoster image URL for the video.

To provide multiple version of sources, you can use array of source objects.

Callback Props

We also provide some callback properties, so you can inject some behaviours directly to the ByteArk Player, and also, to the VideoJS's instance.

NameTypeCallback ParametersDescription
onPlayerLoadedFunction-Callback function to be called when loaded player's resources.
onPlayerLoadingErrorFunction({error: ByteArkPlayerContainerError, originalError: ByteArkPlayerError)Callback function to be called when there're an error about loading player.
onPlayerSetupFunction-Callback function to be called when player is setup.
onPlayerSetupErrorFunction({error: ByteArkPlayerContainerError, originalError: ByteArkPlayerError)Callback function to be called when there're an error when setup player.
onReadyFunction(player: ByteArkPlayer)Callback function to be called when a player instance is ready.
onPlayerCreatedFunction(player: ByteArkPlayer)Callback function to be called when a player instance is created.

Advanced Props

We also provide some ways to custom the appearance of the video placeholder, and some advance behaviours.

NameTypeDescription
placeholderTemplateTemplateRefCustom video placeholder. This should be an Angular TemplateRef.
createPlayerFunctionFunctionCustom video instance. This function should return a VideoJS's player instance.
lazyloadBooleanThe player loads its asset files once it got rendered on the webpage. By passing this prop, the player then loads its asset files once the user clicked on the player instead.
playerEndpointStringEndpoint to the video player (without version part).
playerJsFileNameStringFile name of player's JS.
playerCssFileNameStringFile name of player's CSS.
import { Component } from "@angular/core";
import { ByteArkPlayerContainer, type ByteArkPlayerContainerProps } from "@byteark/byteark-player-angular";

@Component({
  selector: "app-sample-blog",
  standalone: true,
  imports: [ByteArkPlayerContainer],
  template: ` <byteark-player-container [options]="options"></byteark-player-container> `,
})
export class SampleBlogComponent {
  title = "ByteArk Player Container | Sample Blog";
  options: ByteArkPlayerContainerProps = {
    playerEndpoint: "https://my-custom-endpoint.byteark.com",
    lazyload: true,
    fluid: true,
    autoplay: false,
    aspectRatio: "16:9",
    poster: "https://example.com/poster.jpg",
    sources: [
      {
        src: "https://example.com/video.mp4",
        type: "video/mp4",
        title: "Sample Video",
      },
    ],
  };
}

Advanced Usages

Controlling Players

You may access the player instance from onReady callback parameter.

import { Component } from "@angular/core";
import { ByteArkPlayerContainer, type ByteArkPlayerContainerProps, type ByteArkPlayer } from "@byteark/byteark-player-angular";

@Component({
  selector: "app-sample-blog",
  standalone: true,
  imports: [ByteArkPlayerContainer],
  template: ` <byteark-player-container [options]="options"></byteark-player-container> `,
})
export class SampleBlogComponent {
  title = "ByteArk Player Container | Sample Blog";
  player: ByteArkPlayer | null = null;
  options: ByteArkPlayerContainerProps = {
    playerEndpoint: "https://my-custom-endpoint.byteark.com",
    lazyload: true,
    fluid: true,
    autoplay: false,
    aspectRatio: "16:9",
    poster: "https://example.com/poster.jpg",
    sources: [
      {
        src: "https://example.com/video.mp4",
        type: "video/mp4",
        title: "Sample Video",
      },
    ],
  };
  onReady(player: ByteArkPlayer) {
    this.player = player;
  }
}

Using VideoJS Plugins

You can use VideoJS plugins with ByteArk Player Container.

import { Component } from "@angular/core";
import { ByteArkPlayerContainer, type ByteArkPlayerContainerProps } from "@byteark/byteark-player-angular";

@Component({
  selector: "app-sample-blog",
  standalone: true,
  imports: [ByteArkPlayerContainer],
  template: ` <byteark-player-container [options]="options"></byteark-player-container> `,
})
export class SampleBlogComponent {
  title = "ByteArk Player Container | Sample Blog";
  options: ByteArkPlayerContainerProps = {
    playerEndpoint: "https://my-custom-endpoint.byteark.com",
    lazyload: true,
    fluid: true,
    autoplay: false,
    aspectRatio: "16:9",
    poster: "https://example.com/poster.jpg",
    sources: [
      {
        src: "https://example.com/video.mp4",
        type: "video/mp4",
        title: "Sample Video",
      },
    ],
  };
  onReady(player: ByteArkPlayer) {
    // The player is ready! Initialize plugins here.
  }
}

Request Media/Encryption with credentials

import { Component } from "@angular/core";
import { ByteArkPlayerContainer, type ByteArkPlayerContainerProps } from "@byteark/byteark-player-angular";

@Component({
  selector: "app-sample-blog",
  standalone: true,
  imports: [ByteArkPlayerContainer],
  template: ` <byteark-player-container [options]="options"></byteark-player-container> `,
})
export class SampleBlogComponent {
  title = "ByteArk Player Container | Sample Blog";
  options: ByteArkPlayerContainerProps = {
    playerEndpoint: "https://my-custom-endpoint.byteark.com",
    lazyload: true,
    fluid: true,
    autoplay: false,
    aspectRatio: "16:9",
    poster: "https://example.com/poster.jpg",
    sources: [
      {
        src: "https://example.com/video.mp4",
        type: "video/mp4",
        title: "Sample Video",
      },
    ],
    html5: {
      hlsjs: {
        xhrSetup: function (xhr: XMLHttpRequest, url: string) {
          xhr.withCredentials = true;
        },
      },
    },
  };
  onReady(player: ByteArkPlayer) {
    // The player is ready! Initialize plugins here.
  }
}

Customize Placeholder

You can customize the player's placeholder before the player is ready.

import { Component, ViewChild, TemplateRef } from "@angular/core";
import { ByteArkPlayerContainer, type ByteArkPlayerContainerProps } from "@byteark/byteark-player-angular";
import { CustomPlaceholderComponent } from "./custom-placeholder.component";

@Component({
  selector: "app-sample-blog",
  standalone: true,
  imports: [ByteArkPlayerContainer, CustomPlaceholderComponent],
  template: ` <div class="aspect-video" style="position: relative; width: 100%; height: 0; padding-bottom: 56.25%">
    <byteark-player-container [options]="options"></byteark-player-container>
    <ng-template #placeholderTemplateRef>
      <custom-placeholder [playerProps]="options" (clickPlaceholder)="onClickPlaceholder()" />
    </ng-template>
  </div>`,
})
export class SampleBlogComponent {
  title = "ByteArk Player Container | Sample Blog";
  @ViewChild("placeholderTemplateRef", { static: true }) placeholderTemplateRef!: TemplateRef<unknown>;

  options: ByteArkPlayerContainerProps = {
    playerEndpoint: "https://my-custom-endpoint.byteark.com",
    lazyload: true,
    fluid: true,
    autoplay: false,
    aspectRatio: "16:9",
    poster: "https://example.com/poster.jpg",
    sources: [
      {
        src: "https://example.com/video.mp4",
        type: "video/mp4",
        title: "Sample Video",
      },
    ],
    placeholderTemplate: this.placeholderTemplate,
  };

  async onClickPlaceholder() {
    await this.player?.play();
  }

  ngOnInit() {
    this.options.placeholderTemplate = this.placeholderTemplate;
  }
}

License

MIT © ByteArk Co. Ltd.