ApsaraVideo VOD:Aliplayer API Reference

Nom

Type

Description

id

String

ID de l'élément DOM du conteneur externe du lecteur.

source

String

Lorsque vous utilisez la lecture basée sur une URL, spécifiez l'URL de la vidéo avec cette propriété.

vid

String

L'ID du média pour le service ApsaraVideo Media Processing.

playauth

String

L'identifiant de lecture. Pour obtenir des instructions sur la manière d'obtenir un identifiant de lecture, consultez Obtenir un identifiant de lecture.

customVodServer

String

Un domaine personnalisé pour le proxy VOD (pris en charge dans le mode de lecture VidAuth version 2.32.0 et ultérieure). Vous devez déployer un service de proxy de requête dédié. Lorsque le domaine VOD par défaut (*.aliyuncs.com) est inaccessible, le lecteur bascule automatiquement vers votre service de proxy. Cela évite le détournement par les FAI et améliore la stabilité et le taux de réussite de la lecture.

playConfig

JSON

Paramètres personnalisés utilisés lors de la lecture avec Vid (VidAuth ou VidSts). Ceux-ci sont transmis à l'API VOD. Pour les champs pris en charge et les descriptions des paramètres, consultez Paramètres PlayConfig personnalisés pour la lecture multimédia. Valeur d'exemple :

{"PlayDomain":"vod.test_domain","PreviewTime":"20","MtsHlsUriToken":"yqCD7******oVjslp5Q"}

authTimeout

Number

La période de validité de l'URL de lecture vidéo obtenue à l'aide de Vid (VidAuth ou VidSts). Unité : secondes. Par défaut : 7200.

Assurez-vous que cette valeur dépasse la durée réelle de la vidéo pour éviter que l'URL de lecture n'expire avant la fin de la lecture.

height

String

La hauteur du lecteur. Valeurs valides :

• 100 %

• 100px

width

String

La largeur du lecteur. Valeurs valides :

• 100 %

• 100px

autoSize

Boolean | String

Ajuste automatiquement la taille du lecteur pour l'adapter au contenu vidéo. Valeurs valides : 'height' ou 'width'.

Par exemple, définissez width: '500px' et autoSize: 'height'. Le lecteur conserve une largeur fixe de 500 px et ajuste sa hauteur en fonction du rapport d'aspect de la vidéo.

Ou définissez height: '500px' et autoSize: 'width'. Le lecteur conserve une hauteur fixe de 500 px et ajuste sa largeur en fonction du rapport d'aspect de la vidéo.

Remarque : autoSize: true équivaut à autoSize: 'height'. Le redimensionnement automatique de la hauteur est la valeur par défaut.

videoWidth

String

La largeur de la vidéo. Pour plus d'informations, consultez Définir le mode d'affichage.

videoHeight

String

La hauteur de la vidéo. Pour plus d'informations, consultez Définir le mode d'affichage.

preload

Boolean

Le lecteur se charge automatiquement.

cover

String

L'image de couverture par défaut du lecteur. Saisissez une URL d'image valide. Ce paramètre ne prend effet que lorsque autoplay est défini sur false.

isLive

Boolean

Indique si le contenu est une diffusion en direct. Lorsqu'elle est activée, les utilisateurs ne peuvent pas faire glisser la barre de progression. Par défaut : false. Définissez sur true pour les diffusions en direct.

autoplay

Boolean

Activez la lecture automatique pour le lecteur. La lecture automatique échoue sur les appareils mobiles. Valeurs valides :

• true (par défaut) : active la lecture automatique.

• false : désactive la lecture automatique.

autoplayPolicy

Object

Le lecteur prend en charge une politique adaptative pour la lecture automatique en sourdine. Cette propriété ne prend effet que lorsque autoplay est défini sur true. Un exemple de configuration est le suivant :

autoplayPolicy: {
      fallbackToMute: true, // Repli sur la lecture automatique en sourdine si la lecture automatique audible échoue. Par défaut : false.
      showUnmuteBtn: true, // Affiche un grand bouton de réactivation du son lorsque la lecture automatique en sourdine est active. Par défaut : true.
    }

rePlay

Boolean

Active la lecture en boucle automatique.

useH5Prism

Boolean

Utilise le lecteur HTML5.

playsinline

Boolean

Active la lecture en ligne pour HTML5. Certains navigateurs Android ne prennent pas en charge cette fonctionnalité.

skinRes

Url

L'URL de l'image du thème. Nous ne recommandons pas de modifier ce champ. Pour personnaliser le thème, consultez Personnaliser le thème du lecteur.

skinLayout

Array | Boolean

Configurez la disposition des composants de l'interface utilisateur. Omettez cette propriété pour utiliser la disposition par défaut. Définissez sur false pour masquer tous les composants de l'interface utilisateur. Pour plus d'informations, consultez Configurer la propriété skinLayout.

skinLayoutIgnore

Array

Liste des composants de l'interface utilisateur à masquer. Consultez Référence des paramètres des composants VOD pour les noms des composants. Exemple de configuration :

skinLayoutIgnore: [
  'bigPlayButton', // Masque le grand bouton de lecture.
  'controlBar.fullScreenButton' // Masque le bouton plein écran dans la barre de contrôle (utilisez la notation par points pour les composants imbriqués).
]

controlBarVisibility

String

Implémentation du panneau de contrôle. Les valeurs valides incluent les suivantes :

• click : vous pouvez cliquer sur la zone du lecteur.

• hover (par défaut) : s'affiche lorsque l'utilisateur survole la zone du lecteur.

• always : affiche toujours la barre de contrôle.

• Never : masque l'intégralité du panneau de contrôle.

showBarTime

Number

Temps en millisecondes avant que la barre de contrôle ne se masque automatiquement.

enableSystemMenu

Boolean

Active le menu contextuel système. Par défaut : false.

format

String

Spécifiez le format de l'URL de lecture. Valeurs valides :

• mp4

• hls ou m3u8

• flv

• mp3

Par défaut : vide.

mediaType

String

Spécifiez s'il faut renvoyer l'audio ou la vidéo. Pris en charge uniquement lors de l'utilisation de la lecture basée sur vid. Par défaut : video. Valeurs valides :

• video : Vidéo.

• audio : Formats audio uniquement, tels que les fichiers MP4 contenant uniquement de l'audio.

qualitySort

String

Spécifiez l'ordre de tri. Pris en charge uniquement lors de l'utilisation de la lecture Vid + PlayAuth. Valeurs valides :

• desc : Tri par ordre décroissant (du plus grand au plus petit).

• asc : Tri par ordre croissant (du plus petit au plus grand).

Par défaut : asc.

definition

String

Définissez les définitions vidéo à afficher. Séparez plusieurs définitions par des virgules (,). Exemple : 'FD,LD'. Il s'agit d'un sous-ensemble des définitions disponibles pour le vid spécifié. Valeurs valides :

• FD (basse définition)

• LD (définition standard)

• HD (haute définition)

• HD (ultra-haute définition)

• OD (qualité originale)

• 2K (2K)

• 4K (4K)

defaultDefinition

String

Définissez la définition vidéo par défaut. Celle-ci doit être l'une des définitions disponibles pour le vid spécifié. Valeurs valides :

• FD (basse définition)

• LD (définition standard)

• SD (Standard Definition)

• HD (ultra-haute définition)

• OD (qualité originale)

• 2K (2K)

• 4K (4K)

autoPlayDelay

Number

Délai avant le début de la lecture. Unité : secondes.

language

String

Définissez la langue pour l'internationalisation. Par défaut : zh-cn. Si omis, la langue du navigateur est utilisée. Valeurs valides :

• zh-cn : Chinois

• en-us : Anglais

languageTexts

JSON

Textes d'internationalisation personnalisés au format JSON. Les clés doivent correspondre à la valeur de la propriété language. Exemple : {jp:{Play:"Play"}}. Pour obtenir la liste complète des clés, reportez-vous à la Structure JSON.

snapshotWatermark

Object

Configurez les filigranes pour les captures d'écran des lecteurs HTML5.

useHlsPluginForSafari

Boolean

Activez le plugin HLS pour les navigateurs Safari, à l'exception de Safari 11. Valeurs valides :

• true : Activer.

• false (par défaut) : Désactiver.

enableStashBufferForFlv

Boolean

Activez la mise en cache de la lecture pour le format FLV dans les lecteurs HTML5. Cette option s'applique uniquement à la diffusion en direct. Valeurs valides :

• true (par défaut) : Activer.

• false : Désactiver.

stashInitialSizeForFlv

Number

Taille initiale du cache pour le format FLV dans les lecteurs HTML5. Cette option s'applique uniquement à la diffusion en direct. Par défaut : 32 Ko.

Une valeur plus faible améliore la vitesse de démarrage. Toutefois, si la valeur est trop petite, la lecture risque de saccader après un court instant.

loadDataTimeout

Number

Délai en secondes avant d'inviter l'utilisateur à passer à une définition inférieure en raison de la mise en mémoire tampon. Par défaut : 20.

waitingTimeout

Number

Délai maximal de mise en mémoire tampon. Un message d'erreur s'affiche si ce délai est dépassé. Unité : secondes. Par défaut : 60.

diagnosisButtonVisible

Boolean

Affichez le bouton de diagnostic. Valeurs valides :

• true (par défaut) : Afficher le bouton.

• false : Masquer le bouton.

disableSeek

Boolean

Désactivez la navigation via la barre de progression. Valeurs valides :

• true : Désactiver.

• false (par défaut) : Ne pas désactiver.

encryptType

Number

Activez le chiffrement vidéo Alibaba Cloud (chiffrement privé). Par défaut : 0. Valeurs valides :

• 0 : Lire les vidéos non chiffrées.

• 1 : Lire les vidéos chiffrées de manière privée.

progressMarkers

Array

Un tableau d'objets de marqueurs de progression.

vodRetry

Number

Nombre de tentatives en cas d'échec de la lecture VOD. Par défaut : 3.

liveRetry

Number

Nombre de tentatives en cas d'échec de la lecture en direct. Par défaut : 5.

hlsFrameChasing

Boolean

Activez la poursuite d'images pour la diffusion en direct HLS. Valeurs valides :

• true : Activer la poursuite d'images.

• false (par défaut) : Désactiver la poursuite d'images.

chasingFirstParagraph

Number

Durée du premier segment de poursuite d'images. Unité : secondes. Par défaut : 20.

chasingSecondParagraph

Number

Durée du deuxième segment de poursuite d'images. Unité : secondes. Par défaut : 40.

chasingFirstSpeed

Number

Vitesse de lecture pour le premier segment de poursuite d'images. Par défaut : 1,1×.

chasingSecondSpeed

Number

Vitesse de lecture pour le deuxième segment de poursuite d'images. Par défaut : 1,2×.

hlsOption.maxLiveSyncPlaybackRate

Number

Définissez la vitesse de lecture pour la poursuite d'images en diffusion en direct HLS. Par défaut : 1 (pas de poursuite d'images).

• Exemple de configuration :

  hlsOption: {
    maxLiveSyncPlaybackRate: 1,5, // Définir la vitesse de lecture pour la poursuite d'images.
    liveSyncDurationCount: 3 // Définir le nombre de segments qui déclenchent la poursuite d'images.
  }

• Signification de l'exemple : Lorsque la latence de la diffusion en direct dépasse la durée de 3 segments, le lecteur lit à une vitesse de 1,5× pour rattraper son retard et se maintenir à 3 segments derrière (comme le lecteur a besoin d'un tampon pour gérer les fluctuations du réseau, vous devez modifier la valeur liveSyncDurationCount avec prudence — une valeur trop faible peut provoquer des saccades).

flvFrameChasing

Boolean

Activez la poursuite d'images pour la diffusion en direct FLV. Valeurs valides :

• true : Activer la poursuite d'images.

• false : Désactiver la poursuite d'images.

Par défaut : false.

keyShortCuts

Boolean

Activez les raccourcis clavier. Valeurs valides :

• true : Activer les raccourcis clavier.

• false : Désactiver les raccourcis clavier.

Par défaut : false.

keyFastForwardStep

Number

Intervalle de temps pour l'avance et le retour rapides. Unité : secondes. Par défaut : 10.

rtsFallback

Boolean

Lorsque le navigateur ne prend pas en charge RTS ou lorsque l'extraction du flux RTS échoue, le lecteur bascule automatiquement vers FLV ou HLS. Il privilégie FLV pour une latence plus faible. Si le navigateur ne prend pas en charge FLV, il bascule vers HLS.

Cette fonctionnalité est activée par défaut. Pour la désactiver, définissez ce paramètre sur false.

rtsFallbackType

String

Spécifiez le protocole vers lequel basculer depuis RTS. Valeurs valides : HLS ou FLV. Par défaut, le lecteur effectue une sélection automatique, en privilégiant FLV pour une latence plus faible. Si le navigateur ne prend pas en charge FLV, il bascule vers HLS.

rtsFallbackSource

String

Nous vous recommandons d'utiliser la stratégie de basculement par défaut du lecteur. Toutefois, si vous souhaitez spécifier une URL de flux fixe pour le basculement, utilisez ce paramètre.

traceId

String

Votre identifiant utilisateur unique. Transmettez cette valeur aux points d'instrumentation publics pour suivre la génération des journaux. Par défaut, le SDK Web Player active la génération des journaux. La transmission de traceId aide à identifier les utilisateurs. Si omis, le SDK Web Player génère et stocke un UUID dans le cache du navigateur.

textTracks

Array

Configurez les sous-titres WebVTT externes. Exemple :

textTracks: [
  { kind: 'subtitles', label: 'Chinese', src: 'caption-url', srclang: 'zh-CN', default: true },
  { kind: 'subtitles', label: 'English (US)', src: 'caption-url', srclang: 'en-US' }
],

ratio

Number

Configurez le lecteur pour qu'il s'adapte selon un rapport d'aspect fixe. Par exemple, pour un rapport d'aspect vidéo de 16:9, définissez les paramètres du lecteur sur width: "100%", ratio: 16/9. Cela permet de maintenir le rapport d'aspect du lecteur cohérent avec le contenu vidéo et lui permet de s'adapter proportionnellement lors du redimensionnement de la page.

extLanguageTexts

Object

Le SDK Web Player intègre des textes d'interface en chinois et en anglais. Utilisez cette propriété pour personnaliser le libellé de certains éléments d'interface. Par exemple, pour remplacer l'affichage de HD par 1080p au lieu de high definition :

extLanguageTexts: {
    'zh-cn': {
      'HD': '1080p'
    }
}

speedLevels

Array

Personnalisez la liste des vitesses de lecture. Chaque objet contient une clé (valeur de vitesse) et un texte (libellé affiché dans l'interface). Si ce paramètre est omis, la liste par défaut s'applique. Exemple :

speedLevels: [
  {"key": 0,25, "text": "0.25"},
  {"key": 0,5, "text": "0.5"},
  {"key": 1, "text": "Normal"},
  {"key": 1,25, "text": "1.25"},
  {"key": 1,5, "text": "1.5"},
  {"key": 2,"text": "2"}
]

logo

Array

Configurez des images de logo personnalisées. Exemple :

    logo: [{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.png'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.png'
    }]

Description des champs :

• src : URL de l'image du logo.

• origin : Point de référence utilisé pour le positionnement. Valeurs valides :

  • box : Conteneur du lecteur

  • content : Contenu vidéo

• width/height : Dimensions du logo exprimées en pourcentage (calculées par rapport à origin). Si une seule dimension est spécifiée, l'autre s'ajuste proportionnellement.

• position : Position relative au sein de origin. Valeurs valides :

  • top-left : Coin supérieur gauche

  • top-right : Coin supérieur droit

  • bottom-left : Coin inférieur gauche

  • bottom-right : Coin inférieur droit

• offsetX/offsetY : Décalage par rapport à la position, exprimé en pourcentage (calculé par rapport à origin).

license

Object

Pour utiliser les fonctionnalités à valeur ajoutée telles que Surveillance de la qualité de lecture (héritée), Dépannage ponctuel ou Lecture vidéo H.265/H.266, soumettez d'abord le Formulaire de demande de services à valeur ajoutée pour le SDK Web Player afin d'obtenir une licence. Intégrez ensuite la licence comme suit :

// domain is the domain you entered when applying for the license.
// key is the license key.
license: {
    domain: "example.com",
    key: "example-key"
  }

mute

Boolean

Activez la lecture en sourdine. Configurez ce paramètre pour permettre la lecture automatique muette lorsque les navigateurs bloquent l'autoplay. Pour plus de détails, consultez Fonctionnalités avancées.

clickPause

Boolean

Cliquez sur la zone vidéo pour mettre en pause ou reprendre la lecture.

• true : Activer.

• false : Désactiver.

Valeur par défaut : true sur ordinateur, false sur mobile. N'utilisez pas ce paramètre conjointement avec dbClickSkip afin d'éviter les conflits d'interaction.

disablePip

Boolean

Masquez le bouton Picture-in-Picture (PiP) natif du navigateur.

env

String

Par défaut, les données de télémétrie du lecteur sont envoyées vers le centre de données en Chine. Si vous devez respecter des exigences de conformité pour les données hors de Chine, définissez env: 'SEA' pour envoyer les données vers le centre de données de Singapour.

watchStartTime

Number

Utilisez ce paramètre seul pour définir l'heure de début de la lecture.

Associez-le à watchEndTime pour activer la lecture sur une plage horaire. Les utilisateurs ne peuvent lire et naviguer qu'à l'intérieur de la plage spécifiée.

Unité : secondes

watchEndTime

Number

Associez ce paramètre à watchStartTime pour activer la lecture sur une plage horaire. Les utilisateurs ne peuvent lire et naviguer qu'à l'intérieur de la plage spécifiée.

Si cette valeur est inférieure à watchStartTime, watchStartTime est ignoré.

Unité : secondes

start

Number

Utilisez ce paramètre avec end pour extraire un segment de la vidéo. Par exemple, si la vidéo originale dure 60 secondes et que vous définissez start: 10 et end: 30, le lecteur affiche une vidéo de 20 secondes commençant à la 10e seconde de la vidéo originale.

end

Number

Utilisez ce paramètre avec start pour extraire un segment de la vidéo. Par exemple, si la vidéo originale dure 60 secondes et que vous définissez start: 10 et end: 30, le lecteur affiche une vidéo de 20 secondes commençant à la 10e seconde de la vidéo originale.

dbClickFullscreen

Boolean

Activez le double-clic pour passer en plein écran. Activé par défaut sur ordinateur.

longPressFastForward

Boolean

Activez l'avance rapide par appui long (mobile uniquement). Valeurs valides :

• true (par défaut) : Activer.

• false : Désactiver.

dbClickSkip

Boolean

Double-cliquez à gauche pour revenir en arrière, double-cliquez à droite pour avancer rapidement (mobile uniquement). Valeurs valides :

• true (par défaut) : Activer.

• false : Désactiver.

N'utilisez pas ce paramètre conjointement avec clickPause afin d'éviter les conflits d'interaction.

enableMockFullscreen

Boolean

Activez le pseudo-plein écran basé sur CSS. Par défaut, le lecteur appelle l'API plein écran du navigateur. Sur iOS et certains navigateurs Android, le lecteur système prend le contrôle du plein écran, ce qui peut entraîner des problèmes d'interface. Activez ce paramètre pour éviter cette prise de contrôle. Valeur par défaut : false.

watermark

Object

Configurez des filigranes dynamiques. Exemple :

watermark: {
  enable: true,
  text: 'Copyright ©2026',
  mode: 'BULLET'
}

Description des champs :

• enable : Activer le filigrane dynamique.

• text : Texte à afficher en tant que filigrane.

• mode : Mode du filigrane. Valeurs valides :

  • BULLET : Défilement (par défaut).

  • GHOST : Clignotement aléatoire.

• direction : Direction du mouvement. Valeurs valides :

  • RTL : De droite à gauche (par défaut).

  • LTR : De gauche à droite.

  • STATIC : Statique (valide uniquement pour le mode GHOST).

• speed : Vitesse de déplacement. Plage : 0~100. Plus la valeur est élevée, plus le déplacement est rapide. Valeur par défaut : 50 pour BULLET, 30 pour GHOST.

• interval : Délai en millisecondes entre la disparition et la réapparition du filigrane. Valeur par défaut : 3000.

• duration : Durée d'affichage de chaque apparition du filigrane (uniquement pour le mode GHOST). Valeur par défaut : 5000 (millisecondes).

• opacity : Transparence du texte du filigrane. Plage : 0~1. Valeur par défaut : 0,5.

• fontSize : Taille de police du texte du filigrane. Valeur CSS font-size. Valeur par défaut : 14px.

• fontColor : Couleur du texte du filigrane. Toute valeur de couleur CSS valide. Valeur par défaut : #FFFFFF.

• top : Distance entre le haut du conteneur et la zone du filigrane. Prend en charge les valeurs en pixels (par exemple, 50) ou en pourcentage (par exemple, '20 %').

• bottom : Distance entre le bas du conteneur et la zone du filigrane. Prend en charge les valeurs en pixels ou en pourcentage.

• left : Distance entre la gauche du conteneur et la zone du filigrane. Prend en charge les valeurs en pixels ou en pourcentage (uniquement pour le mode GHOST).

• right : Distance entre la droite du conteneur et la zone du filigrane. Prend en charge les valeurs en pixels ou en pourcentage (uniquement pour le mode GHOST).

memoryPlay

Object

Pour activer la reprise de lecture, ajoutez l'option memoryPlay à la configuration du lecteur. Exemple :

// Resume playback configuration
    memoryPlay: {
        enable: true, // Enable resume playback.
        autoSeek: false // Automatically jump to the remembered position.
    }

Description des champs :

• enable : Activer la reprise de lecture. Valeurs valides :

  • false (par défaut) : Désactiver la reprise de lecture.

  • true : Activer la reprise de lecture.

• autoSeek : Passer automatiquement à la position mémorisée. Valeurs valides :

  • false (par défaut) : Afficher une invite demandant à l'utilisateur s'il souhaite sauter à la position (recommandé).

  • true : Sauter à la position mémorisée et afficher une invite après le chargement de la vidéo.

getTimeFunction/saveTimeFunction sont utilisés pour les scénarios nécessitant un contrôle personnalisé de la progression de la lecture (comme la synchronisation multi-appareils). S'ils sont omis, le lecteur stocke par défaut la progression dans localStorage.

• getTimeFunction : Récupérer l'heure mémorisée depuis un emplacement de stockage personnalisé. Signature de la fonction : (videoKey) => number｜Promise<number>.

• saveTimeFunction : Enregistrer l'heure de lecture actuelle. Signature de la fonction : (videoKey, currentTime) => void.

menuMode

String

Définissez l'emplacement d'affichage des commandes de vitesse de lecture, de définition, de sous-titres et de piste audio. Valeurs valides :

• fold (par défaut) : Placer dans le sous-menu Paramètres.

• expand : Afficher dans la barre de contrôle (menu principal).

refreshUrl

(expiredUrl: string) => Promise<string>

Actualisation automatique en cas d'expiration de l'URL. Lorsque l'URL signée CDN expire pendant la lecture (l'en-tête de réponse HTTP 403 contient l'horodatage d'expiration), le rappel de service est automatiquement appelé pour obtenir la nouvelle URL et reprendre la lecture. L'URL est retentée jusqu'à 3 fois. La fonction reçoit l'adresse de lecture actuellement expirée et renvoie une Promise résolue vers une nouvelle adresse disponible. Si elle n'est pas configurée, la fonction n'est pas activée. Exemple ci-dessous :

new Aliplayer({
  source: 'YOUR_SOURCE_URL',
  refreshUrl: async (expiredUrl) => {
      // await fetch new url ...
      return 'NEW_URL'
  }
});