Skip to content

Commit f19a86d

Browse files
jdreetzjdreetz
authored
Add types (#1106)
* add Typesscript types * add missing type info * updates types * add generics to getCuePoints. Add type tests. Fix event name to map typing. enforce vimeo embed properties needs either clip id or url * add missing new line at end of file * remove extra comment chracters * revise VideoQuality to VideoQualityId to reduce ambiguity, but define as alias type for string to allow for non standard qualities * provide more complete embed parameter lists, including descriptions and default values. update type tests to validate constructor options. remove id or url embed params requirement, as it's not enforceable at type checking time, because of ambiguity of first argument to Player constructor, but apply id/url embed params enforcement for loadVideo, where it is required * use Required TS helper for id/url enforcement. it's more expressive than previous syntax.
1 parent 229f49d commit f19a86d

6 files changed

Lines changed: 1278 additions & 0 deletions

File tree

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,9 @@
2727
"directories": {
2828
"lib": "src/"
2929
},
30+
"types": "types/player.d.ts",
3031
"files": [
32+
"types/",
3133
"src",
3234
"dist"
3335
],

‎types/errors.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/** Base error type for Vimeo Player errors */
2+
export interface VimeoError extends Error {
3+
name: string;
4+
}
5+
6+
/** Error when a value is out of the acceptable range */
7+
export interface RangeError extends VimeoError {
8+
name: "RangeError";
9+
}
10+
11+
/** Error when a feature is not supported */
12+
export interface UnsupportedError extends VimeoError {
13+
name: "UnsupportedError";
14+
}
15+
16+
/** Error when an invalid parameter is provided */
17+
export interface InvalidParameterError extends VimeoError {
18+
name: "InvalidParameterError";
19+
}
20+
21+
/** Error when a requested item cannot be found */
22+
export interface NotFoundError extends VimeoError {
23+
name: "NotFoundError";
24+
}
25+
26+
/** Error when a password is required */
27+
export interface PasswordError extends VimeoError {
28+
name: "PasswordError";
29+
}
30+
31+
/** Error when a video is private */
32+
export interface PrivacyError extends VimeoError {
33+
name: "PrivacyError";
34+
}

‎types/events.ts‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
import {
2+
Seconds,
3+
VolumeLevel,
4+
PlaybackRate,
5+
CameraProperties,
6+
VimeoTextTrackCuePoint,
7+
ProportionPercent,
8+
VideoQualityId,
9+
VimeoCuePoint,
10+
Pixels,
11+
} from "./formats";
12+
13+
export enum PlayerEvent {
14+
/** Triggered when video playback is initiated */
15+
Play = "play",
16+
17+
/** Triggered when the video pauses */
18+
Pause = "pause",
19+
20+
/** Triggered any time the video playback reaches the end. Note: when loop is turned on, the ended event will not fire */
21+
Ended = "ended",
22+
23+
/** Triggered as the currentTime of the video updates. Generally fires every 250ms, but may vary depending on the browser */
24+
TimeUpdate = "timeupdate",
25+
26+
/** Triggered as the video is loaded. Reports back the amount of the video that has been buffered */
27+
Progress = "progress",
28+
29+
/** Triggered when the player starts seeking to a specific time. A timeupdate event will also be fired at the same time */
30+
Seeking = "seeking",
31+
32+
/** Triggered when the player seeks to a specific time. A timeupdate event will also be fired at the same time */
33+
Seeked = "seeked",
34+
35+
/** Triggered when the active text track (captions/subtitles) changes. The values will be null if text tracks are turned off */
36+
TextTrackChange = "texttrackchange",
37+
38+
/** Triggered when the active cue for the current text track changes. It also fires when the active text track changes. There may be multiple cues active */
39+
CueChange = "cuechange",
40+
41+
/** Triggered when the current chapter changes */
42+
ChapterChange = "chapterchange",
43+
44+
/** Triggered when the current time hits a registered cue point */
45+
CuePoint = "cuepoint",
46+
47+
/** Triggered when a new video is loaded in the player */
48+
Loaded = "loaded",
49+
50+
/** Triggered when video metadata is loaded */
51+
LoadedMetadata = "loadedmetadata",
52+
53+
/** Triggered when the volume in the player changes. Some devices do not support setting the volume independently from system volume */
54+
VolumeChange = "volumechange",
55+
56+
/** Triggered when the playback rate changes. The ability to change rate can be disabled by the creator */
57+
PlaybackRateChange = "playbackratechange",
58+
59+
/** Triggered when the set quality changes */
60+
QualityChange = "qualitychange",
61+
62+
/** Triggered when the player enters or exits fullscreen */
63+
FullscreenChange = "fullscreenchange",
64+
65+
/** Triggered when any of the camera properties change for 360° videos */
66+
CameraChange = "camerachange",
67+
68+
/** Triggered when the intrinsic size of the media changes */
69+
Resize = "resize",
70+
71+
/** Triggered when the player enters picture-in-picture */
72+
EnterPictureInPicture = "enterpictureinpicture",
73+
74+
/** Triggered when the player leaves picture-in-picture */
75+
LeavePictureInPicture = "leavepictureinpicture",
76+
77+
/** Triggered when some kind of error is generated in the player */
78+
Error = "error",
79+
80+
/** Triggered when buffering starts in the player. This is also triggered during preload and while seeking */
81+
BufferStart = "bufferstart",
82+
83+
/** Triggered when buffering ends in the player. This is also triggered at the end of preload and seeking */
84+
BufferEnd = "bufferend",
85+
86+
/** Triggered when the duration attribute has been updated */
87+
DurationChange = "durationchange",
88+
89+
/** Triggered when the availability of remote playback changes */
90+
RemotePlaybackAvailabilityChanged = "remoteplaybackavailabilitychanged",
91+
92+
/** Triggered when the player is attempting to connect to a remote playback device */
93+
RemotePlaybackConnecting = "remoteplaybackconnecting",
94+
95+
/** Triggered when the player has successfully connected to a remote playback device */
96+
RemotePlaybackConnected = "remoteplaybackconnected",
97+
98+
/** Triggered when the player has disconnected from a remote playback device */
99+
RemotePlaybackDisconnected = "remoteplaybackdisconnected",
100+
101+
/** Triggered when a hotspot is clicked */
102+
InteractiveHotspotClicked = "interactivehotspotclicked",
103+
104+
/** Triggered when the overlay panel (buttons or images) within the interactive overlay is clicked */
105+
InteractiveOverlayPanelClicked = "interactiveoverlaypanelclicked"
106+
}
107+
108+
export interface VimeoEvent {
109+
duration: Seconds;
110+
percent: ProportionPercent;
111+
seconds: Seconds;
112+
}
113+
114+
export interface FullscreenChangeEvent {
115+
fullscreen: boolean;
116+
}
117+
118+
export interface TextTrackChangeEvent {
119+
kind: string | undefined;
120+
label: string | undefined;
121+
language: string | undefined;
122+
}
123+
124+
export interface ChapterChangeEvent {
125+
startTime: Seconds;
126+
/** Title of the chapter */
127+
title: string;
128+
/**
129+
* The index property of each chapter is the place it holds
130+
* in the order of all the chapters. It starts at 1.
131+
*/
132+
index: number;
133+
}
134+
135+
export interface CuePointEvent<T = Record<string, unknown>> extends VimeoCuePoint<T> {}
136+
137+
export interface CueChangeEvent extends TextTrackChangeEvent {
138+
cues: VimeoTextTrackCuePoint[];
139+
}
140+
141+
export interface LoadedEvent {
142+
id: number;
143+
}
144+
145+
export interface DurationChangeEvent {
146+
duration: Seconds;
147+
}
148+
149+
export interface VolumeChangeEvent {
150+
volume: VolumeLevel;
151+
muted: boolean;
152+
}
153+
154+
export interface PlaybackRateChangeEvent {
155+
playbackRate: PlaybackRate;
156+
}
157+
158+
export interface QualityChangeEvent {
159+
quality: VideoQualityId;
160+
}
161+
162+
export interface CameraChangeEvent extends CameraProperties {}
163+
164+
export interface ResizeEvent {
165+
videoWidth: Pixels;
166+
videoHeight: Pixels;
167+
}
168+
169+
export interface ErrorEvent {
170+
name: string;
171+
message: string;
172+
method: string;
173+
}
174+
175+
export interface InteractiveHotspotClickEvent {
176+
action: 'seek' | 'event' | 'none' | 'overlay' | 'url';
177+
actionPreference: {
178+
/**
179+
* on `event`, `overlay`, `seek`, `url` action
180+
*/
181+
pauseOnAction?: boolean;
182+
/**
183+
* on `overlay` action
184+
*/
185+
overlayId?: number;
186+
/**
187+
* on `seek` action
188+
*/
189+
seekTo?: number;
190+
/**
191+
* on `url` action
192+
*/
193+
url?: string;
194+
};
195+
currentTime: number;
196+
customPayloadData: any | null;
197+
hotspotId: number;
198+
}
199+
export interface InteractiveOverlayPanelClickEvent {
200+
action: 'seek' | 'clickthrough' | 'close' | 'event' | 'none';
201+
actionPreference: {
202+
/** on `close`, `seek` action */
203+
pauseOnAction?: boolean;
204+
/** on `seek` action */
205+
seekTo?: number;
206+
/** on `clickthrough` action */
207+
url?: string;
208+
};
209+
currentTime: Seconds;
210+
customPayloadData: unknown | null;
211+
overlayId: number;
212+
panelId: string;
213+
}
214+
215+
/**
216+
* Utility type that maps an event's data type to a generic version if supported
217+
*/
218+
export type EventDataWithGenerics<E extends keyof PlayerEventMap | PlayerEvent, T> = E extends keyof PlayerEventMap
219+
? PlayerEventMap[E] extends CuePointEvent<any>
220+
? CuePointEvent<T>
221+
: PlayerEventMap[E]
222+
: PlayerEventMap[E extends PlayerEvent ? E : never];
223+
224+
/** Maps event names to their corresponding event data types */
225+
export interface PlayerEventMap {
226+
[PlayerEvent.Play]: VimeoEvent;
227+
play: VimeoEvent;
228+
[PlayerEvent.Pause]: VimeoEvent;
229+
pause: VimeoEvent;
230+
[PlayerEvent.Ended]: VimeoEvent;
231+
ended: VimeoEvent;
232+
[PlayerEvent.TimeUpdate]: VimeoEvent;
233+
timeupdate: VimeoEvent;
234+
[PlayerEvent.Progress]: VimeoEvent;
235+
progress: VimeoEvent;
236+
[PlayerEvent.Seeking]: VimeoEvent;
237+
seeking: VimeoEvent;
238+
[PlayerEvent.Seeked]: VimeoEvent;
239+
seeked: VimeoEvent;
240+
[PlayerEvent.TextTrackChange]: TextTrackChangeEvent;
241+
texttrackchange: TextTrackChangeEvent;
242+
[PlayerEvent.ChapterChange]: ChapterChangeEvent;
243+
chapterchange: ChapterChangeEvent;
244+
[PlayerEvent.CueChange]: CueChangeEvent;
245+
cuechange: CueChangeEvent;
246+
[PlayerEvent.CuePoint]: CuePointEvent;
247+
cuepoint: CuePointEvent;
248+
[PlayerEvent.Loaded]: LoadedEvent;
249+
loaded: LoadedEvent;
250+
[PlayerEvent.LoadedMetadata]: { duration: number };
251+
loadedmetadata: { duration: number };
252+
[PlayerEvent.VolumeChange]: VolumeChangeEvent;
253+
volumechange: VolumeChangeEvent;
254+
[PlayerEvent.PlaybackRateChange]: PlaybackRateChangeEvent;
255+
playbackratechange: PlaybackRateChangeEvent;
256+
[PlayerEvent.QualityChange]: QualityChangeEvent;
257+
qualitychange: QualityChangeEvent;
258+
[PlayerEvent.FullscreenChange]: FullscreenChangeEvent;
259+
fullscreenchange: FullscreenChangeEvent;
260+
[PlayerEvent.CameraChange]: CameraChangeEvent;
261+
camerachange: CameraChangeEvent;
262+
[PlayerEvent.Resize]: ResizeEvent;
263+
resize: ResizeEvent;
264+
[PlayerEvent.EnterPictureInPicture]: void;
265+
enterpictureinpicture: void;
266+
[PlayerEvent.LeavePictureInPicture]: void;
267+
leavepictureinpicture: void;
268+
[PlayerEvent.Error]: ErrorEvent;
269+
error: ErrorEvent;
270+
[PlayerEvent.BufferStart]: void;
271+
bufferstart: void;
272+
[PlayerEvent.BufferEnd]: void;
273+
bufferend: void;
274+
[PlayerEvent.DurationChange]: DurationChangeEvent;
275+
durationchange: DurationChangeEvent;
276+
[PlayerEvent.RemotePlaybackAvailabilityChanged]: void;
277+
remoteplaybackavailabilitychanged: void;
278+
[PlayerEvent.RemotePlaybackConnecting]: void;
279+
remoteplaybackconnecting: void;
280+
[PlayerEvent.RemotePlaybackConnected]: void;
281+
remoteplaybackconnected: void;
282+
[PlayerEvent.RemotePlaybackDisconnected]: void;
283+
remoteplaybackdisconnected: void;
284+
[PlayerEvent.InteractiveHotspotClicked]: InteractiveHotspotClickEvent;
285+
interactivehotspotclicked: InteractiveHotspotClickEvent;
286+
[PlayerEvent.InteractiveOverlayPanelClicked]: InteractiveOverlayPanelClickEvent;
287+
interactiveoverlaypanelclicked: InteractiveOverlayPanelClickEvent;
288+
}

0 commit comments

Comments
 (0)