npm package: @instructure/studio-player
Description: Next generation media player for Instructure
Latest version: 1.8.3

# studio-player

## Sources

- `sources` renamed to `src`: can be an url or an array of objects with the following props:
  - `src` `type` `width` `height`
- instead of `label` you have to provide the `width` and `height`, this is important, because the player will be able to collect the qualities based on these.

example:

```js
[
  {
    src: 'my-video1.mp4',
    type: 'video/mp4',
    width: 1920,
    height: 1080,
  },
  {
    src: 'my-video2.mp4',
    type: 'video/mp4',
    width: 1280,
    height: 720,
  },
];
```

### Captions

- `tracks` has been renamed to `captions`
- `id` and `kind` is not used
- `type` should be the subtitle format, `vtt` or `srt`

example:

```js
[
  {
    src: 'my-captions-en.srt',
    label: 'English',
    language: 'en',
    type: 'srt',
  },
  {
    src: 'my-captions-es.srt',
    label: 'Spanish',
    language: 'es',
    type: 'srt',
  },
];
```

### Kebab menu elements

The `kebabMenuElements` prop can be used to display a kebab menu in the top right corner of the player.
There are 4 predefined icons currently: `media`, `transcript`, `share`, `delete`.

```js
[
  {
    id: 'media',
    text: 'Download Media',
    icon: 'media',
    onClick: id => console.log('Clicked', id),
  },
  {
    id: 'transcript',
    text: 'Download Transcript',
    icon: 'transcript',
    onClick: id => console.log('Clicked', id),
  },
];
```

### Manage captions menu

If you provide a function as the `onCaptionsDelete` prop, the _Manage Captions_ menu will appear in the captions menu, and for each caption there will be a menu option to delete that caption.

```js
function deleteCaption(caption: CaptionMetaData) {
  // implement your caption deletion logic, alerts, etc.
}

...

<StudioPlayer
  ...
  onCaptionsDelete={deleteCaption}
  ...
/>
```

### Deprecated props compared to old Media Player

these props are no longer used and you can remove them from the code:

- `onLoadedMetadata`
- `captionPosition`
- `autoShowCaption`

## Translations

Handling translations is manual for now since we don't except too frequent changes to it.

### Upload

One would need to do the proper `assume` commands to get the rights to access our S3 bucket. Please ask this from an engineer in team.

After one having correct credentials,

```bash
./i18n-utils/upload.sh
```

Upon proper upload one must see `Upload completed successfully!` message.

Notice: It might appear that after script runs your source translation file is changed, it sorts keys in alphabetical order. In that case, please commit that change!

### Download

One would need to do the proper `assume` commands to get the rights to access our S3 bucket. Please ask this from an engineer in team.

After one having correct credentials,

```bash
./i18n-utils/download.sh
```

This will download the translated content and put it in the correct folder. Feel free to upload to a branch and make a PR from it.


## E2E Testing

1. **Setup**
   - Create a `.env` file:
     ```
     SB_BASE_URL="http://localhost"
     SB_PORT="6010"
     ```
2. **Running Tests**

   - `pnpm test:pw` - Runs Playwright tests in Firefox (Storybook starts automatically)
   - `pnpm test:pw:show-report` - View the latest test report

3. **Debugging**

   - One can debug through VS Code extension and tick Show browser option OR
   - `pnpm test:pw <FileName> --debug` which gives a line-by-line debugger

4. **Notes:**

- Using a separate port (e.g. `6010` instead of `6006`) prevents conflicts with your
  development Storybook instance.
- Highly recommended to install [Playwright VS Code](https://marketplace.visualstudio.com/items/?itemName=ms-playwright.playwright) extension,
  also check out [Getting started in VS Code](https://playwright.dev/docs/getting-started-vscode)


## YouTube Education Player

In order to use the YouTube Education Player, you need to provide an encrypted payload as `STORYBOOK_YOUTUBE_ENCRYPTED_PAYLOAD` in `.env` file.

### Generating the Encrypted Payload
1. In tweed `docker.compose.override.yml`, add the `YOUTUBE_EDUCATION_API_KEY` to "YouTube Education (Local)" key from 1password factory reset vault in api namespace.
2. Enable `youtube_pf_edu` feature flag in tweed if you haven't done yet.
3. After restarting the containers, you can generate the encrypted payload by running the following command in api rails console:
   ```ruby
    Account::Account.first.activate!
    metadata = TweedMediaManagement::ExternalMetadata.from_url("<YOUTUBE_VIDEO_URL>")
    media = TweedMediaManagement::Media.create!(user: User::User.first, external_metadata: metadata, title: "some title")
    YoutubeEducationEncryptor.encrypt_embed_config(media)
   ```
4. Copy the generated encrypted payload and set it as `STORYBOOK_YOUTUBE_ENCRYPTED_PAYLOAD` in your `.env` file.

### Playback directly from Notorious
1. First you need to obtain the media id. You can either directly get it from Notorious SiteAdmin or use the Expose Media ID extension in the browser.
2. Once you have the media id, you can generate a playback url by running the following command in notorious web rails console:
   ```ruby
    media = Media.find_by_public_guid("<MEDIA_ID>")
    media.original.transcodings.first.drm_playback_url
   ```
3. Use the generated playback url as the `src`.