Skip to content

Commit 2f65a95

Browse files
TheMissenoOneTheMissenoOne
authored
V7 Audio Player (#12513)
### Description This PR adds comprehensive audio/podcast player support to the video player component (v7). The implementation extends the existing video player infrastructure to handle audio-only content with appropriate UI configurations and styling optimizations. Key Features: - New player-type attribute supporting both VIDEO (default) and AUDIO modes - Audio-specific Kaltura player configuration with customizable ui-conf-id and partner-id - Optimized compact layout for audio players (120–180px height vs standard video aspect ratios) - Automatic player embedding for audio content (no thumbnail click required) - Optional artwork/thumbnail support for audio players - Comprehensive test coverage for audio player functionality Technical Implementation: - Extended video-player-container, video-player-composite, and video-player components with audio support - Added audio-specific styling that removes aspect ratio constraints and reduces container height - Modified thumbnail rendering logic to handle audio players without artwork gracefully - Implemented auto-embed behavior for audio content to provide immediate playback capability ### Changelog New - Added player-type attribute to video player components supporting VIDEO and AUDIO modes - Added ui-conf-id attribute for custom Kaltura player configuration - Added partner-id attribute for custom Kaltura partner ID - Added audio player story to Storybook - Added comprehensive test suite for audio player functionality (audio-player.test.ts) - Added audio-specific styling with compact layout Changed - Modified video player to auto-embed audio content without requiring thumbnail interaction - Updated thumbnail rendering logic to handle audio players with optional artwork - Optimized caption spacing for audio players (1rem top padding) - Enhanced player initialization to support audio-specific Kaltura configurations
1 parent 01a6c4e commit 2f65a95

8 files changed

Lines changed: 1101 additions & 0 deletions

File tree

‎packages/web-components/src/components/audio-player/__stories__/README.stories.mdx‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
3+
<Meta title="Components/Audio Player/Overview" />
4+
5+
# Audio Player
6+
7+
> A dedicated audio-only player component for podcast and audio content playback.
8+
9+
## Overview
10+
11+
The Audio Player is a simplified, standalone component specifically designed for audio-only content. It provides a clean interface for embedding and playing audio files with minimal configuration, separate from the video player component.
12+
13+
## Features
14+
15+
- **Simplified API** - Only requires `media-id` and optional `auto-play`
16+
- **Automatic Embedding** - Audio loads immediately, no click required
17+
- **Autoplay Support** - Respects user preferences and browser policies
18+
- **Multiple Players** - Proper DOM isolation for multiple audio players on the same page
19+
- **Kaltura Integration** - Uses audio-specific configuration by default
20+
- **Accessibility** - ARIA labels and keyboard navigation support
21+
- **Preference Storage** - Remembers user's autoplay preference
22+
- **Error Handling** - Cleanup on failed embeds
23+
24+
## When to Use
25+
26+
Use the Audio Player component when you need to:
27+
28+
- Embed podcast episodes
29+
- Play music tracks
30+
- Deliver audiobook content
31+
- Provide audio lectures or educational materials
32+
- Stream radio shows on-demand
33+
- Present audio interviews and conversations
34+
35+
## Component Structure
36+
37+
The Audio Player consists of three main components:
38+
39+
1. **`<c4d-audio-player>`** - Base UI component
40+
2. **`<c4d-audio-player-composite>`** - State management layer
41+
3. **`<c4d-audio-player-container>`** - Redux/Kaltura integration layer
42+
43+
## Basic Usage
44+
45+
```html
46+
<c4d-audio-player-container
47+
media-id="1_abc123"
48+
auto-play>
49+
</c4d-audio-player-container>
50+
```
51+
52+
## Properties
53+
54+
| Property | Attribute | Type | Default | Description |
55+
|----------|-----------|------|---------|-------------|
56+
| `mediaId` | `media-id` | `string` | `''` | **Required.** The Kaltura media ID for the audio content |
57+
| `autoPlay` | `auto-play` | `boolean` | `false` | Enable autoplay (respects user preferences and browser policies) |
58+
| `muted` | `muted` | `boolean` | `false` | Start with audio muted |
59+
| `audioTitle` | `audio-title` | `string` | `undefined` | Custom title for the audio content |
60+
| `uiConfId` | `ui-conf-id` | `string` | `'57792222'` | Kaltura UI configuration ID (defaults to audio player config) |
61+
| `partnerId` | `partner-id` | `string` | `'1773841'` | Kaltura partner ID |
62+
63+
## Events
64+
65+
### `c4d-audio-player-playback-state-changed`
66+
67+
Fired when the playback state changes (play/pause).
68+
69+
**Event Detail:**
70+
```typescript
71+
{
72+
mediaId: string;
73+
isPlaying: boolean;
74+
}
75+
```
76+
77+
## Examples
78+
79+
### With Custom Title
80+
81+
```html
82+
<c4d-audio-player-container
83+
media-id="1_abc123"
84+
audio-title="Episode 42: The Future of Web Components">
85+
</c4d-audio-player-container>
86+
```
87+
88+
### Multiple Players
89+
90+
```html
91+
<c4d-audio-player-container
92+
media-id="1_track1"
93+
audio-title="Track 1">
94+
</c4d-audio-player-container>
95+
96+
<c4d-audio-player-container
97+
media-id="1_track2"
98+
audio-title="Track 2">
99+
</c4d-audio-player-container>
100+
```
101+
102+
## Styling
103+
104+
### CSS Parts
105+
106+
The component exposes the following CSS parts for styling:
107+
108+
- `audio-container` - The main audio player container
109+
110+
**Example:**
111+
```css
112+
c4d-audio-player::part(audio-container) {
113+
border-radius: 8px;
114+
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
115+
}
116+
```
117+
118+
## Differences from Video Player
119+
120+
| Feature | Video Player | Audio Player |
121+
|---------|-------------|--------------|
122+
| **Thumbnail** | Yes | No |
123+
| **Click-to-play** | Yes | No (auto-embed) |
124+
| **Aspect Ratio** | Configurable | Fixed height (120-180px) |
125+
| **Player Type** | VIDEO | AUDIO |
126+
| **UI Config** | Video config | Audio config (57792222) |
127+
| **Complexity** | Full-featured | Simplified |
128+
129+
## Migration from Video Player
130+
131+
If you're currently using the video player for audio content:
132+
133+
**Before:**
134+
```html
135+
<c4d-video-player-container-v7
136+
video-id="1_abc123"
137+
player-type="AUDIO"
138+
auto-play>
139+
</c4d-video-player-container-v7>
140+
```
141+
142+
**After:**
143+
```html
144+
<c4d-audio-player-container
145+
media-id="1_abc123"
146+
auto-play>
147+
</c4d-audio-player-container>
148+
```
149+
150+
## Browser Support
151+
152+
- Chrome (latest)
153+
- Firefox (latest)
154+
- Safari (latest)
155+
- Edge (latest)
156+
157+
**Note:** Autoplay behavior may vary based on browser policies. Most browsers require user interaction before allowing autoplay with sound.
158+
159+
## Accessibility
160+
161+
The Audio Player component follows accessibility best practices:
162+
163+
- Proper ARIA labels for screen readers
164+
- Keyboard navigation support
165+
- Focus management
166+
- Semantic HTML structure
167+
168+
## Related Components
169+
170+
- [Video Player V7](../?path=/docs/components-video-player-v7--overview) - Full video player with video support
171+
- [Video Player](../?path=/docs/components-video-player--overview) - Legacy video player (V2)
172+
173+
## Feedback
174+
175+
Help us improve this component by [opening an issue](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new) or [contributing](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/blob/main/.github/CONTRIBUTING.md).

‎packages/web-components/src/components/audio-player/__stories__/audio-player.stories.ts‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
/**
2+
* @license
3+
*
4+
* Copyright IBM Corp. 2020, 2025
5+
*
6+
* This source code is licensed under the Apache-2.0 license found in the
7+
* LICENSE file in the root directory of this source tree.
8+
*/
9+
10+
import { html } from 'lit';
11+
import { ifDefined } from 'lit/directives/if-defined.js';
12+
import '../audio-player-container';
13+
import readme from './README.stories.mdx';
14+
15+
export default {
16+
title: 'Components/Audio Player',
17+
parameters: {
18+
...readme.parameters,
19+
percy: {
20+
skip: true,
21+
},
22+
},
23+
};
24+
25+
export const Default = (args) => {
26+
const { mediaId, autoPlay, muted, audioTitle, uiConfId, partnerId } =
27+
args?.['c4d-audio-player-container'] ?? {};
28+
29+
return html`
30+
<c4d-audio-player-container
31+
media-id="${ifDefined(mediaId)}"
32+
?auto-play="${autoPlay}"
33+
?muted="${muted}"
34+
audio-title="${ifDefined(audioTitle)}"
35+
ui-conf-id="${ifDefined(uiConfId)}"
36+
partner-id="${ifDefined(partnerId)}">
37+
</c4d-audio-player-container>
38+
`;
39+
};
40+
41+
Default.story = {
42+
name: 'Default',
43+
parameters: {
44+
knobs: {
45+
'c4d-audio-player-container': () => ({
46+
mediaId: '1_9h94wo6b',
47+
autoPlay: false,
48+
muted: false,
49+
audioTitle: '',
50+
uiConfId: '',
51+
partnerId: '',
52+
}),
53+
},
54+
propsSet: {
55+
default: {
56+
'c4d-audio-player-container': {
57+
mediaId: '1_9h94wo6b',
58+
autoPlay: false,
59+
muted: false,
60+
audioTitle: '',
61+
uiConfId: '',
62+
partnerId: '',
63+
},
64+
},
65+
},
66+
},
67+
};
68+
69+
export const WithAutoplay = (args) => {
70+
const { mediaId, autoPlay, muted, audioTitle, uiConfId, partnerId } =
71+
args?.['c4d-audio-player-container'] ?? {};
72+
73+
return html`
74+
<c4d-audio-player-container
75+
media-id="${ifDefined(mediaId)}"
76+
?auto-play="${autoPlay}"
77+
?muted="${muted}"
78+
audio-title="${ifDefined(audioTitle)}"
79+
ui-conf-id="${ifDefined(uiConfId)}"
80+
partner-id="${ifDefined(partnerId)}">
81+
</c4d-audio-player-container>
82+
`;
83+
};
84+
85+
WithAutoplay.story = {
86+
name: 'With Autoplay',
87+
parameters: {
88+
knobs: {
89+
'c4d-audio-player-container': () => ({
90+
mediaId: '1_9h94wo6b',
91+
autoPlay: true,
92+
muted: false,
93+
audioTitle: '',
94+
uiConfId: '',
95+
partnerId: '',
96+
}),
97+
},
98+
propsSet: {
99+
default: {
100+
'c4d-audio-player-container': {
101+
mediaId: '1_9h94wo6b',
102+
autoPlay: true,
103+
muted: false,
104+
audioTitle: '',
105+
uiConfId: '',
106+
partnerId: '',
107+
},
108+
},
109+
},
110+
},
111+
};

0 commit comments

Comments
 (0)