### Install BeyondWords Player NPM Package

Source: https://docs.beyondwords.io/docs-and-guides/migration-guides/player-legacy

Installs the BeyondWords player package. Use 'npm add' for the latest version or 'npm install --save' for the legacy package.

```javascript
npm add @beyondwords/player
```

```javascript
npm install --save @beyondwords/audio-player
```

--------------------------------

### Player Model Schema and Example

Source: https://docs.beyondwords.io/api-reference/player/show-1

This entry details the player model schema, outlining various configuration options for content, player styling, video settings, playlists, and ads. It includes a complete example of a player response payload.

```APIDOC
PlayerModel:
  description: OK
  type: path
  refIdentifier: '#/components/schemas/playerModel'
  examples:
    example:
      summary: A player sample response
      value:
        language: en_US
        content:
          - id: 52acb1c0-9681-4138-9d74-1b7234f80922
            title: Content title
            source_id: example-source-id
            source_url: https://example.com/my-article
            author: John Smith
            image_url: https://example.com/image.jpeg
            audio:
              - id: 123
                content_type: audio/mpeg
                url: https://example.com/audio.mp3
                duration: 10000
            video:
              - id: 456
                content_type: video/mp4
                url: https://example.com/video.mp4
                duration: 10000
            segments:
              - marker: title-marker
                start_time: 3
                duration: 2997
              - marker: first-paragraph-marker
                start_time: 3000
                duration: 7000
            ads_enabled: true
        settings:
          player_style: standard
          player_title: My project
          call_to_action: Listen to this article
          image_url: https://example.com/image.jpeg
          theme: auto
          dark_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          light_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          video_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          title_enabled: false
          image_enabled: false
          persistent_ad_image: false
          widget_style: standard
          widget_position: auto
          segment_playback_enabled: true
          segment_highlights_enabled: true
          skip_button_style: seconds-15-30
          intro_url: https://example.com/intro.mp3
          outro_url: https://example.com/outro.mp3
          intro_outro_enabled: false
          download_button_enabled: false
          logo_icon_enabled: true
        video_settings:
          enabled: true
          logo_image_url: https://example.com/logo.png
          logo_image_position: top-right
          background_color: white
          text_background_color: 'rgba(255, 255, 255, 0.88)'
          text_color: black
          text_highlight_color: '#0cf'
          text_fonts:
            - Inter-Medium.ttf
            - NotoSansSC-Medium.ttf
            - NotoSansJP-Medium.ttf
            - NotoSansHebrew-Medium.ttf
            - NotoSansTamil-Medium.ttf
          text_lines: null
          text_align: start
          waveform_color: 'linear-gradient(to right, red, blue)'
          content_image_enabled: true
          playback_mode: cycle
          cycle_time: 15000
        playlist:
          id: 555
          title: My playlist
          type: manual
          image_url: https://example.com/image.jpeg
          content_limit: 25
        ads:
          - id: 7
            type: custom
            placement: pre-roll
            vast_url: null
            title: Ad title
            click_through_url: https://example.com/click-through-url
            media_url: https://example.com/advert.mp3
            media:
              - id: 100
                content_type: audio/mpeg
                url: https://example.com/transcoded_advert.mp3
                duration: 15000
            theme: null
            dark_theme: null
            light_theme: null
components:
  schemas:
    playerModel:
      properties:
        background_color:
          type: string
        icon_color:
          type: string

```

--------------------------------

### Rule Model Example

Source: https://docs.beyondwords.io/api-reference/rules/create

Provides a concrete example of a 'ruleModel' object, illustrating its structure and typical values. This example includes an ID, key, value, type, associated project, content details, and timestamps.

```APIDOC
refIdentifier: '#/components/schemas/ruleModel'
components:
  schemas:
    ruleModel:
      properties:
        id: { type: integer }
        key: { type: string }
        value: { type: string }
        type: { type: string }
        project:
          type: object
          properties:
            id: { type: integer }
            name: { type: string }
        content:
          type: object
          properties:
            id: { type: string }
            title: { type: string }
        created: { type: string }
        updated: { type: string }
examples:
  example:
    summary: A sample rule response
    value:
      id: 1
      key: CO2
      value: Carbon dioxide
      type: substitute
      project:
        id: 1
        name: Test project
      content:
        id: d8414aee-4171-419e-be42-bd57e9e2ccd2
        title: >-
          Unveiling the Catastrophic Consequences of Excess Carbon
          Dioxide Emissions
      created: 2023-01-01 00:00:00 UTC
      updated: 2023-01-01 00:00:05 UTC
description: successful
deprecated: false
type: path
```

--------------------------------

### API Example: adModel Response

Source: https://docs.beyondwords.io/api-reference/ads/show

Provides a concrete example of a full ad model response, illustrating the structure and typical values for various properties, including media assets and theme settings.

```APIDOC
examples:
  example:
    summary: A sample ad response
    value:
      id: 1
      type: custom
      enabled: true
      placement: pre-roll
      vast_url: null
      title: My advert title
      click_through_url: https://example.com
      image_url: https://example.com/image.png
      media_url: https://example.com/advert.mp3
      media:
        - id: 123
          content_type: audio/mpeg
          url: https://example.com/transcoded.mp3
          duration: 15000
        - id: 124
          content_type: application/vnd.apple.mpegurl
          url: https://example.com/transcoded.m3u8
          duration: 15000
      theme: dark
      dark_theme:
        text_color: '#fff'
        background_color: '#333'
        icon_color: '#ff0'
      light_theme: null
      video_theme: null
      time_range:
        start: 2023-12-01 00:00:00 UTC
        end: 2023-12-31 23:59:59 UTC
      created: 2023-01-01 00:00:00 UTC
      updated: 2023-01-01 00:00:05 UTC
```

--------------------------------

### Install via NPM - Add Package

Source: https://docs.beyondwords.io/docs-and-guides/distribution/player/overview

Install the BeyondWords player NPM package into your project using the npm command.

```javascript
npm add @beyondwords/player
```

--------------------------------

### projectModel Schema and Example

Source: https://docs.beyondwords.io/api-reference/projects/create

Defines the structure of a project object returned by the API, including its ID, name, language, and status. An example demonstrates a typical project response.

```APIDOC
components:
  schemas:
    projectModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the project
        name:
          type: string
          description: Name of the project
        language:
          type: string
          description: Language code for the project (e.g., en_US)
        auto_publish_enabled:
          type: boolean
          description: Flag indicating if auto-publishing is enabled
        avatar_url:
          type: string
          format: url
          description: URL of the project's avatar
        created:
          type: string
          format: date-time
          description: Timestamp when the project was created
        updated:
          type: string
          format: date-time
          description: Timestamp when the project was last updated
      example:
        summary: A sample project response
        value:
          id: 1
          name: My project
          language: en_US
          auto_publish_enabled: true
          avatar_url: https://example.com/avatar.jpg
          created: "2022-01-02 23:59:59 UTC"
          updated: "2022-03-04 00:00:00 UTC"

```

--------------------------------

### Player Model Schema Example

Source: https://docs.beyondwords.io/api-reference/player/show-3

Provides a detailed example of the player model response structure, illustrating the expected format for content, playback settings, and associated metadata. This schema is crucial for integrating BeyondWords content playback into applications.

```APIDOC
Player Model Response Example:
  refIdentifier: '#/components/schemas/playerModel'
  description: OK
  deprecated: false
  type: path
  examples:
    example:
      summary: A player sample response
      value:
        language: en_US
        content:
          - id: 52acb1c0-9681-4138-9d74-1b7234f80922
            title: Content title
            source_id: example-source-id
            source_url: https://example.com/my-article
            author: John Smith
            image_url: https://example.com/image.jpeg
            audio:
              - id: 123
                content_type: audio/mpeg
                url: https://example.com/audio.mp3
                duration: 10000
            video:
              - id: 456
                content_type: video/mp4
                url: https://example.com/video.mp4
                duration: 10000
            segments:
              - marker: title-marker
                start_time: 3
                duration: 2997
              - marker: first-paragraph-marker
                start_time: 3000
                duration: 7000
            ads_enabled: true
        settings:
          player_style: standard
          player_title: My project
          call_to_action: Listen to this article
          image_url: https://example.com/image.jpeg
          theme: auto
          dark_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          light_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          video_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          title_enabled: false
          image_enabled: false
          persistent_ad_image: false
          widget_style: standard
          widget_position: auto
          segment_playback_enabled: true
          segment_highlights_enabled: true
          skip_button_style: seconds-15-30
          intro_url: https://example.com/intro.mp3
          outro_url: https://example.com/outro.mp3
          intro_outro_enabled: false
          download_button_enabled: false
          logo_icon_enabled: true
        video_settings:
          enabled: true
          logo_image_url: https://example.com/logo.png
          logo_image_position: top-right
          background_color: white
          text_background_color: rgba(255, 255, 255, 0.88)
          text_color: black
          text_highlight_color: '#0cf'
          text_fonts:
            - Inter-Medium.ttf
            - NotoSansSC-Medium.ttf
            - NotoSansJP-Medium.ttf
            - NotoSansHebrew-Medium.ttf
            - NotoSansTamil-Medium.ttf
          text_lines: null
          text_align: start
          waveform_color: linear-gradient(to right, red, blue)
          content_image_enabled: true
          playback_mode: cycle
          cycle_time: 15000
        playlist:
          id: 555
          title: My playlist
          type: manual
          image_url: https://example.com/image.jpeg
          content_limit: 25
        ads:
          - id: 7
            type: custom
            placement: pre-roll
            vast_url: null
            title: Ad title
            click_through_url: https://example.com/click-through-url
            media_url: https://example.com/advert.mp3
            media:
              - id: 100
                content_type: audio/mpeg
                url: https://example.com/transcoded_advert.mp3
                duration: 15000
            theme: null
            dark_theme: null
            light_theme: null
```

--------------------------------

### Player Model Schema Example

Source: https://docs.beyondwords.io/api-reference/player/show-2

Provides a detailed example of the player model response structure, illustrating the expected format for content, playback settings, and associated metadata. This schema is crucial for integrating BeyondWords content playback into applications.

```APIDOC
Player Model Response Example:
  refIdentifier: '#/components/schemas/playerModel'
  description: OK
  deprecated: false
  type: path
  examples:
    example:
      summary: A player sample response
      value:
        language: en_US
        content:
          - id: 52acb1c0-9681-4138-9d74-1b7234f80922
            title: Content title
            source_id: example-source-id
            source_url: https://example.com/my-article
            author: John Smith
            image_url: https://example.com/image.jpeg
            audio:
              - id: 123
                content_type: audio/mpeg
                url: https://example.com/audio.mp3
                duration: 10000
            video:
              - id: 456
                content_type: video/mp4
                url: https://example.com/video.mp4
                duration: 10000
            segments:
              - marker: title-marker
                start_time: 3
                duration: 2997
              - marker: first-paragraph-marker
                start_time: 3000
                duration: 7000
            ads_enabled: true
        settings:
          player_style: standard
          player_title: My project
          call_to_action: Listen to this article
          image_url: https://example.com/image.jpeg
          theme: auto
          dark_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          light_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          video_theme:
            text_color: '#323232'
            background_color: '#FAFAFA'
            icon_color: '#323232'
          title_enabled: false
          image_enabled: false
          persistent_ad_image: false
          widget_style: standard
          widget_position: auto
          segment_playback_enabled: true
          segment_highlights_enabled: true
          skip_button_style: seconds-15-30
          intro_url: https://example.com/intro.mp3
          outro_url: https://example.com/outro.mp3
          intro_outro_enabled: false
          download_button_enabled: false
          logo_icon_enabled: true
        video_settings:
          enabled: true
          logo_image_url: https://example.com/logo.png
          logo_image_position: top-right
          background_color: white
          text_background_color: rgba(255, 255, 255, 0.88)
          text_color: black
          text_highlight_color: '#0cf'
          text_fonts:
            - Inter-Medium.ttf
            - NotoSansSC-Medium.ttf
            - NotoSansJP-Medium.ttf
            - NotoSansHebrew-Medium.ttf
            - NotoSansTamil-Medium.ttf
          text_lines: null
          text_align: start
          waveform_color: linear-gradient(to right, red, blue)
          content_image_enabled: true
          playback_mode: cycle
          cycle_time: 15000
        playlist:
          id: 555
          title: My playlist
          type: manual
          image_url: https://example.com/image.jpeg
          content_limit: 25
        ads:
          - id: 7
            type: custom
            placement: pre-roll
            vast_url: null
            title: Ad title
            click_through_url: https://example.com/click-through-url
            media_url: https://example.com/advert.mp3
            media:
              - id: 100
                content_type: audio/mpeg
                url: https://example.com/transcoded_advert.mp3
                duration: 15000
            theme: null
            dark_theme: null
            light_theme: null
```

--------------------------------

### BeyondWords Player Initialization Properties

Source: https://docs.beyondwords.io/docs-and-guides/migration-guides/player-legacy

Details the configuration properties available for initializing the BeyondWords player, allowing customization of audio content and source tracking.

```APIDOC
BeyondWords.Player Constructor Options:

  - target: string
    CSS selector for the HTML element where the player will be mounted.

  - projectID: string
    Your unique project identifier.

  - contentId: string
    Unique UUID string for the audio content. Can also accept the previous integer audio ID as a string for legacy API migration.

  - sourceId: string
    An externally provided source identifier for a content item. Examples include CMS IDs, RSS `<guid>`, or WordPress post IDs.

  - sourceUrl: string
    The URL containing the source content. Examples include public API submission URLs, RSS `<link>`, or WordPress post URLs.

  - playlistId: string
    The unique identifier for a playlist created via the dashboard or API.
```

--------------------------------

### Making Authenticated API Request (Bash)

Source: https://docs.beyondwords.io/api-reference/overview

Demonstrates how to make a GET request to the BeyondWords API using cURL, including the necessary authentication header. This example shows the basic structure for interacting with the API.

```bash
curl -X GET "https://api.beyondwords.io/v1/endpoint" \
  -H "X-Api-Key: YOUR_API_KEY"
```

--------------------------------

### BeyondWords Player Initialization Options

Source: https://docs.beyondwords.io/docs-and-guides/migration-guides/player-legacy

Configuration options for initializing the BeyondWords Player. These properties control which content is played and how it's identified.

```APIDOC
BeyondWords.Player({
  target: HTMLElement | string, // Optional. The element to append the player to. Defaults to the script's parent element.
  projectId: string, // Required. The unique identifier for your project.
  contentId: string, // Optional. Unique UUID string for the audio content. Can also be the previous integer audio ID as a string.
  sourceId: string, // Optional. Externally provided source identifier (e.g., CMS ID, GUID, post ID).
  sourceUrl: string, // Optional. URL containing the source content (e.g., public URL, RSS link, post URL).
  playlistId: string // Optional. The unique ID for a playlist created in the dashboard or through the API.
})

Parameters:
  target: The DOM element or selector where the player should be rendered. If not specified, the player is appended to the script's parent element.
  projectId: Your unique project identifier, essential for loading the correct audio content.
  contentId: A UUID string that uniquely identifies the audio content. For migration, legacy integer IDs can also be passed as strings.
  sourceId: An external identifier for the content, useful for linking to your content management system or other sources.
  sourceUrl: The web address of the original content, such as a blog post URL or an RSS feed item link.
  playlistId: The identifier for a pre-defined playlist, allowing playback of multiple audio items sequentially.
```

--------------------------------

### Example GET Response (Processed Status with Segments)

Source: https://docs.beyondwords.io/api-reference/content/segments

This JSON shows the API response after the 'auto_segment' content has been processed. The 'status' is 'processed', and the 'segments' array is populated with detailed information for each part of the content, including text, timing, language, and voice used.

```json
{
  "type": "auto_segment",
  "status": "processed",
  "id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
  "title": "<h1>Your content title text</h1>",
  "summary": "<h2>Your content summary text</h2>",
  "body": "<p>Your content body text</p>",
  "source_id": "article-id-in-your-cms",
  "source_url": "https://example.com/some-article",
  "author": "Steve Jobs",
  "image_url": "https://example.com/image.jpeg",
  "audio": [
    {
      "id": 36553942,
      "content_type": "application/x-mpegURL",
      "url": "https://example.com/media.m3u8",
      "duration": 7051
    },
    {
      "id": 36553929,
      "content_type": "audio/mpeg",
      "url": "https://example.com/media_compiled.mp3",
      "duration": 7056
    }
  ],
  "video": [],
  "segments": [
    {
      "marker": "0a2bae2e-542f-498e-95c4-91dfc403eb8b",
      "section": "title",
      "start_time": 45,
      "duration": 1730,
      "id": 95737414,
      "content_type": "text",
      "text": "Your content title text",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_US",
        "name": "English (USA)"
      },
      "voice": {
        "id": 298,
        "name": "Matthew"
      },
      "created": "2023-07-26T05:02:24Z",
      "updated": "2023-07-26T05:02:25Z"
    },
    {
      "marker": "b012ad1b-7366-4ed1-a6f2-b855665065ad",
      "section": "summary",
      "start_time": null,
      "duration": null,
      "id": 95737415,
      "content_type": "text",
      "text": "Your content summary text",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_US",
        "name": "English (USA)"
      },
      "voice": {
        "id": 776,
        "name": "Sara"
      },
      "created": "2023-07-26T05:02:24Z",
      "updated": "2023-07-26T05:02:25Z"
    },
    {
      "marker": "ad212f8f-8356-4059-9ee9-c5b1406f70b7",
      "section": "body",
      "start_time": 1841,
      "duration": 2595,
      "id": 95737416,
      "content_type": "text",
      "text": "Your content summary text",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_US",
        "name": "English (USA)"
      },
      "voice": {
        "id": 776,
        "name": "Sara"
      },
      "created": "2023-07-26T05:02:24Z",
      "updated": "2023-07-26T05:02:25Z"
    },
    {
      "marker": "76bfc232-2755-4da7-86b1-222a66434444",
      "section": "body",
      "start_time": 4503,
      "duration": 2559,
      "id": 95737417,
      "content_type": "text",
      "text": "Your content summary text",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_US",
        "name": "English (USA)"
      },
      "voice": {
        "id": 776,
        "name": "Sara"
      },
      "created": "2023-07-26T05:02:24Z",
      "updated": "2023-07-26T05:02:25Z"
    }
  ],
  "is_copy": false,
  "ads_enabled": true,
  "title_voice_id": null,
  "summary_voice_id": null,
  "body_voice_id": null,
  "metadata": {
    "key": "value"
  },
  "created": "2023-01-01T00:00:00Z",
  "updated": "2023-01-01T00:00:05Z",
  "published": true,
  "publish_date": "2023-01-01T00:00:00Z",
  "auto_segment_updates_enabled": true
}
```

--------------------------------

### BeyondWords manual_segment API Request/Response

Source: https://docs.beyondwords.io/api-reference/content/segments

This section details the structure for creating or updating content items using the 'manual_segment' type. It includes an example POST request for submitting segmented content (text, audio, images) and a corresponding GET response showing the processed output.

```APIDOC
POST Request Example:
```json
{
  "type": "manual_segment",
  "source_id": "example-source-id",
  "source_url": "https://example.com/some-article",
  "author": "Steve Jobs",
  "image_url": "https://example.com/image.jpeg",
  "metadata": {
    "key": "value"
  },
  "segments": [
    {
      "section": "title",
      "marker": "75aa616c-1849-4d70-bb3b-7691cc6310a5",
      "content_type": "text",
      "text": "This is a title",
      "voice": {
        "id": 1
      }
    },
    {
      "section": "body",
      "marker": "75aa616c-1849-4d70-bb3b-7691cc6310a2",
      "content_type": "text",
      "text": "This is a paragraph",
      "voice": {
        "id": 1
      }
    },
    {
      "section": "body",
      "content_type": "image",
      "image_url": "https://example.com/image.jpeg"
    },
    {
      "section": "body",
      "marker": "75aa616c-1849-4d70-bb3b-7691cc6311a5",
      "content_type": "text",
      "text": "This is another paragraph",
      "voice": {
        "id": 1
      }
    },
    {
      "section": "body",
      "marker": "75aa616c-1849-4d71-bb3b-7691cc6310a5",
      "content_type": "audio",
      "audio_url": "https://example.com/audio.mp3"
    },
    {
      "section": "body",
      "marker": "75aa416c-1849-4d70-bb3b-7691cc6310a5",
      "content_type": "text",
      "text": "This is another paragraph",
      "voice": {
        "id": 1
      }
    }
  ],
  "published": true,
  "ads_enabled": false,
  "auto_segment_updates_enabled": false
}
```
```

```APIDOC
GET Response Example:
```json
{
  "id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
  "status": "processed",
  "type": "manual_segment",
  "title": null,
  "summary": null,
  "body": null,
  "source_id": "example-source-id",
  "source_url": "https://example.com/some-article",
  "author": "Steve Jobs",
  "image_url": "https://example.com/image.jpeg",
  "metadata": {
    "key": "value"
  },
  "audio": [
    {
      "id": 1,
      "content_type": "application/vnd.apple.mpegurl",
      "url": "https://example.com/audio.m3u8",
      "duration": 10000
    },
    {
      "id": 2,
      "content_type": "audio/mpeg,",
      "url": "https://example.com/audio.mp3",
      "duration": 10000
    }
  ],
  "video": [],
  "segments": [
    {
      "id": 1,
      "section": "title",
      "marker": "75aa616c-1849-4d70-bb3b-7691cc6310a5",
      "content_type": "text"
    }
  ]
}
```
```

--------------------------------

### Install via embed script

Source: https://docs.beyondwords.io/docs-and-guides/distribution/player/overview

Add the BeyondWords player to your web application by including this script tag. It asynchronously loads the player and initializes it with specified project and content IDs.

```javascript
<script async defer src="https://proxy.beyondwords.io/npm/@beyondwords/player@latest/dist/umd.js"
    onload="new BeyondWords.Player({
        target: this,
        projectId: <ID>,
        contentId: '<ID>'
    })">
</script>
```

--------------------------------

### GET /rules - Retrieve Rules

Source: https://docs.beyondwords.io/api-reference/rules/list

Retrieves a list of rules from the BeyondWords API. Supports filtering by type, preview status, key, scopes, languages, and voices. Rules can be ordered by type, key, value, or creation date, with pagination via limit and offset. Includes examples for successful responses and error handling.

```APIDOC
paths:
  /rules:
    get:
      summary: Retrieve a list of rules
      servers:
        - url: https://api.beyondwords.io/v1
      security:
        - title: apiKey
          parameters:
            query: {}
            header:
              X-Api-Key:
                type: apiKey
            cookie: {}
      parameters:
        query:
          pagination[limit]:
            schema:
              type: integer
              required: false
              description: 'limit' sets the number of results to return in each page.
          pagination[offset]:
            schema:
              type: integer
              required: false
              description: >-
                'offset' sets the first position to return from the results of
                the query. The default is 0, which starts the page at the first
                result.
          order[by]:
            schema:
              type: enum<string>
              enum:
                - type
                - key
                - value
                - created
              required: false
              description: This is used to order rules by type or key or value
          order[dir]:
            schema:
              type: enum<string>
              enum:
                - asc
                - desc
              required: false
              description: >-
                This is used to order analytics in the ascending or descending
                order
          filter[type]:
            schema:
              type: string
              required: false
              description: filter by rule type
          filter[preview_status]:
            schema:
              type: string
              required: false
              description: filter by rule preview status
          filter[key]:
            schema:
              type: string
              required: false
              description: filter by rule key
          filter[scopes]:
            schema:
              type: object
              properties: {}
              required: false
              description: filter items by scopes
            style: deepObject
            explode: true
          filter[languages][]:
            schema:
              type: array
              items:
                type: string
              required: false
              description: filter by languages
          filter[voices][]:
            schema:
              type: array
              items:
                type: integer
              required: false
              description: filter by voices
      responses:
        '200':
          application/json:
            schema:
              $ref: '#/components/schemas/rulesModel'
            examples:
              example:
                summary: Sample list of rules response
                value:
                  - id: 1
                    key: CO2
                    value: United States of America
                    type: Carbon dioxide
                    project:
                      id: 1
                      name: Test project
                    content:
                      id: d8414aee-4171-419e-be42-bd57e9e2ccd2
                      title: >-
                        Unveiling the Catastrophic Consequences of Excess Carbon
                        Dioxide Emissions
                    created: 2023-01-01 00:00:00 UTC
                    updated: 2023-01-01 00:00:05 UTC
                  - id: 2
                    key: Ocasio
                    value: oʊˈkɑːsi.oʊ
                    type: ipa_transcription
                    created: 2023-01-01 00:00:00 UTC
                    updated: 2023-01-01 00:00:05 UTC
                  - id: 3
                    key: NATO
                    type: say_as_word
                    created: 2023-01-01 00:00:00 UTC
                    updated: 2023-01-01 00:00:05 UTC
                  - id: 4
                    key: IPO
                    type: say_as_letter_sequence
                    created: 2023-01-01 00:00:00 UTC
                    updated: 2023-01-01 00:00:05 UTC
            description: OK
        '401':
          application/json:
            schema:
              $ref: '#/components/schemas/errorModel'
            examples:
              example:
                summary: Unauthorized error
                value: {}
components:
  schemas:
    ruleModel:
      type: object
      properties:
        id:
          type: integer
        key:
          type: string
        value:
          type: string
        type:
          type: string
        project:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        content:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
        created:
          type: string
        updated:
          type: string
    rulesModel:
      type: array
      items:
        $ref: '#/components/schemas/ruleModel'
    errorModel:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
        errors:
          type: array
          nullable: true
          items:
            type: object
            properties:
              location:
                type: string
              message:
                type: string

```

--------------------------------

### Install via NPM - Initialize Player

Source: https://docs.beyondwords.io/docs-and-guides/distribution/player/overview

Initialize the BeyondWords player programmatically after importing the package. This involves creating a new Player instance, specifying the target element and content identifiers.

```javascript
import BeyondWords from '@beyondwords/player';

new BeyondWords.Player({ target: '#beyondwords-player', projectID: <ID>, contentId: '<ID>' });
```

--------------------------------

### GET /projects/{id}/voices - BeyondWords API

Source: https://docs.beyondwords.io/api-reference/projects/voices

Retrieves a list of available voices for a specific project. This endpoint requires an API key for authentication and returns a JSON array of voice objects, each detailing properties like ID, name, type, status, and language support. It includes detailed schema definitions and example responses.

```APIDOC
OpenAPI Specification for BeyondWords Voices API:

paths:
  /projects/{id}/voices:
    get:
      summary: Get voices for a project
      servers:
        - url: https://api.beyondwords.io/v1
      operationId: getProjectVoices
      security:
        - apiKey:
            type: http
            scheme: bearer
            bearerFormat: JWT
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: project id
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/voiceModel'
              examples:
                sampleVoiceResponse:
                  summary: A sample voice response
                  value:
                    - id: 1
                      name: James
                      type: premade
                      status: enabled
                      speaker: null
                      script_ids: []
                      speaking_rate: 103
                      languages:
                        - code: en_GB
                          name: English
                          accent: British
                          preview_url: https://example.com/James_en_GB_preview.mp3
                        - code: en_US
                          name: English
                          accent: American
                          preview_url: null
                        - code: en_AU
                          name: English
                          accent: Aussie
                          preview_url: https://example.com/James_en_AU_preview.mp3
                      cloning_consent: null
                      clone_errors: []
                      created: '2022-01-01 00:00:00 UTC'
                      updated: '2022-01-31 12:59:59 UTC'
                      language: en_GB
                      secondary_languages: []
                      service: azure
                      preview_url: https://example.com/James_en_GB_preview.mp3
                      exclusive: false
                      custom: false
                    - id: 1
                      name: Jane
                      type: professional
                      status: deprecated
                      speaker:
                        id: 123
                        first_name: Jane
                        last_name: Doe
                        avatar_url: https://example.com/Jane_avatar.jpg
                      script_ids: []
                      speaking_rate: 98
                      languages:
                        - code: en_AU
                          name: English
                          accent: Aussie
                          preview_url: https://example.com/Jane_en_AU_preview.mp3
                      cloning_consent: https://example.com/i_agree_to_voice_cloning.mp3
                      clone_errors: []
                      created: '2022-01-01 00:00:00 UTC'
                      updated: '2022-01-31 12:59:59 UTC'
                      language: en_AU
                      secondary_languages: []
                      service: azure
                      preview_url: https://example.com/Jane_en_AU_preview.mp3
                      exclusive: true
                      custom: true

components:
  schemas:
    voiceModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object
        name:
          type: string
          description: The name of the voice
        type:
          type: string
          description: The type of the voice
          enum:
            - premade
            - instant
            - professional
        status:
          type: string
          description: The status of the voice
          enum:
            - draft
            - recording
            - processing
            - review
            - enabled
            - deprecated
            - disabled
            - unavailable
        preview_statuses:
          type: string
          description: The preview status of the voice for its primary language
          enum:
            - processing
            - processed
        speaker:
          type: object
          description: The speaker of the voice
          nullable: true
          properties:
            id:
              type: integer
              description: Unique identifier for the object
            first_name:
              type: string
              description: The first name of the speaker
            last_name:
              type: string
              description: The last name of the speaker
            avatar_url:
              type: string
              description: The image URL of the speaker
              nullable: true
            created:
              type: string
              format: date-time
              description: Time at which the object was created (ISO 8601)
            updated:
              type: string
              format: date-time
              description: Time at which the object was updated (ISO 8601)
        script_ids:
          type: array
          items:
            type: integer
        languages:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: ISO 639-1 language code
              name:
                type: string
                description: The name of the language
              accent:
                type: string
                description: The accent of the language
              preview_url:
                type: string
                description: URL for a preview of the voice in this language
                nullable: true
        cloning_consent:
          type: string
          description: URL to the voice cloning consent document
          nullable: true
        clone_errors:
          type: array
          items:
            type: string
        created:
          type: string
          format: date-time
          description: Time at which the object was created (ISO 8601)
        updated:
          type: string
          format: date-time
          description: Time at which the object was updated (ISO 8601)
        language:
          type: string
          description: The primary language code for the voice
        secondary_languages:
          type: array
          items:
            type: string
        service:
          type: string
          description: The TTS service provider used for the voice
        preview_url:
          type: string
          description: URL for a preview of the voice
        exclusive:
          type: boolean
          description: Indicates if the voice is exclusive
        custom:
          type: boolean
          description: Indicates if the voice is custom

```

--------------------------------

### Initialize BeyondWords Player

Source: https://docs.beyondwords.io/docs-and-guides/migration-guides/player-legacy

Initializes the BeyondWords player by importing the library and creating a new Player instance. Requires specifying the target element and essential IDs for content playback.

```javascript
import BeyondWords from '@beyondwords/player';

new BeyondWords.Player({ target: '#beyondwords-player', projectID: <ID>, contentId: '<ID>' });
```

--------------------------------

### Project Configuration Schema

Source: https://docs.beyondwords.io/api-reference/player/show

Defines the structure for project configuration, detailing various properties for UI customization, theme settings, and video playback. This schema outlines the expected data types, enumerations, and constraints for each configuration option.

```APIDOC
Project Configuration:
  type: object
  properties:
    widget_settings:
      type: object
      description: Settings for the widget display.
      properties:
        type: string
        image_url:
          type: string
        theme:
          type: string
          enum:
            - auto
            - dark
            - light
        dark_theme:
          type: object
          properties:
            text_color: string
            background_color: string
            icon_color: string
            highlight_color: string
        light_theme:
          type: object
          properties:
            text_color: string
            background_color: string
            icon_color: string
            highlight_color: string
        video_theme:
          type: object
          properties:
            text_color: string
            background_color: string
            icon_color: string
        title_enabled: boolean
        image_enabled:
          type: boolean
          deprecated: true
        widget_style:
          type: string
          enum:
            - none
            - small
            - standard
            - large
            - video
        widget_position:
          type: string
          enum:
            - auto
            - left
            - center
            - right
        segment_playback_enabled: boolean
        segment_highlights_enabled: boolean
        skip_button_style: string
        intro: string
          nullable: true
        outro: string
          nullable: true
        intro_outro_enabled:
          type: boolean
          deprecated: true
        download_button_enabled: boolean
        logo_icon_enabled: boolean
        analytics_enabled: boolean
        analytics_uuid_enabled: boolean
        analytics_url: string
        analytics_custom_url:
          type: string
          nullable: true
        analytics_id: integer
        analytics_tag_enabled: boolean
        analytics_tag:
          type: string
          nullable: true
    video_settings:
      allOf:
        - type: object
          description: >-
            Video settings for the project of the first content item.
            See the swagger schema for /v1/video_settings for more
            information.
          properties:
            enabled: boolean
            logo_image_url:
              type: string
              nullable: true
            logo_image_position:
              type: string
              enum:
                - top-left
                - top-right
            background_color: string
            text_background_color: string
            text_color: string
            text_highlight_color: string
            text_fonts:
              type: array
              items: string
            text_lines:
              type: integer
              nullable: true
            text_align: string
```