SDK de PHP de la API de Video de Vonage

Descripción general del SDK
Referencia API
Descargar
Muestras
GitHub

El SDK de OpenTok para PHP ofrece métodos para:

Generación sesiones y fichas para OpenTok Applications desarrolladas en PHP
Trabajar con Archivos de OpenTok
Trabajar con Retransmisiones en directo de OpenTok
Trabajar con Interconexión SIP de OpenTok
Envío de señales a los clientes conectados a una sesión
Desconectar a los clientes de las sesiones
Forzar a los clientes de una sesión a desconectarse o silenciar el audio publicado
Trabajar con OpenTok Conector de audio

Instalación

Programa de composición (recomendado):

Composer ayuda a gestionar las dependencias de los proyectos PHP. Encontrarás más información aquí: http://getcomposer.org

Añade este paquete (opentok/opentok) a tu composer.json o ejecute lo siguiente en la línea de comandos línea de comandos:

composer require opentok/opentok ^4.0

Uso

Inicialización de

Este paquete sigue el PSR-4 Estándar de autocarga. Si estás utilizando Composer para la instalación, solo tienes que incluir el autoloader generado:

require "<projectpath>/vendor/autoload.php";

Una vez cargados los archivos del SDK, se inicializa un OpenTok\OpenTok objeto con tu propia API clave y secreto de API.

use OpenTok\OpenTok;

$opentok = new OpenTok($apiKey, $apiSecret);

Opciones de inicialización

El OpenTok\OpenTok Estos objetos solo permiten modificar algunos valores cuando surgen necesidades especiales, como la necesidad de indicar un centro de datos diferente o cambiar el tiempo de espera del cliente HTTP subyacente. Para estas situaciones, puedes pasar una matriz de opciones adicionales como tercer parámetro.

Ofrecemos las siguientes opciones:

apiUrl - Cambia el dominio al que apunta el SDK. Útil cuando se necesita seleccionar un centro de datos específico o apuntar a una versión simulada de la API para realizar pruebas.
client - Cliente de API personalizado que hereda de OpenTok\Utils\Client, útil para personalizar un cliente HTTP
timeout - Cambia el tiempo de espera predeterminado de HTTP, que por defecto es indefinido. Puedes indicar un número de segundos para modificar el tiempo de espera.

use OpenTok\OpenTok;
use MyCompany\CustomOpenTokClient;

$options = [
    'apiUrl' => 'https://custom.domain.com/',
    'client' => new CustomOpenTokClient(),
    'timeout' => 10,
]
$opentok = new OpenTok($apiKey, $apiSecret, $options);

Creación de sesiones

Para crear una sesión de OpenTok, utiliza el createSession($options) método del OpenTok\OpenTok clase. En $options es una matriz opcional que se utiliza para especificar lo siguiente:

Configuración para determinar si la sesión utilizará el OpenTok Media Router o intentará enviar las transmisiones directamente entre los clientes.
Establecer si la sesión creará automáticamente archivos (implica el uso de sesión enrutada).
Especificar una sugerencia de ubicación.

El getSessionId() método del OpenTok\Session La instancia devuelve el ID de sesión, que se utiliza para identificar la sesión en las bibliotecas de cliente de OpenTok.

use OpenTok\MediaMode;
use OpenTok\ArchiveMode;

// Create a session that attempts to use peer-to-peer streaming:
$session = $opentok->createSession();

// A session that uses the OpenTok Media Router, which is required for archiving:
$session = $opentok->createSession(array( 'mediaMode' => MediaMode::ROUTED ));

// A session with a location hint:
$session = $opentok->createSession(array( 'location' => '12.34.56.78' ));

// An automatically archived session:
$sessionOptions = array(
    'archiveMode' => ArchiveMode::ALWAYS,
    'mediaMode' => MediaMode::ROUTED
);
$session = $opentok->createSession($sessionOptions);


// Store this sessionId in the database for later use
$sessionId = $session->getSessionId();

Generación de fichas

Una vez creada una sesión, puedes empezar a generar tokens para que los clientes los utilicen al conectarse a ella. Puedes generar un token llamando a la función generateToken($sessionId, $options) método del OpenTok\OpenTok clase, o llamando a la generateToken($options) en el OpenTok\Session instancia tras crearla. La $options El parámetro es una matriz opcional que se utiliza para configurar el rol, el tiempo de caducidad y los datos de conexión del token. Para el control del diseño en archivos y retransmisiones, también se puede configurar la lista inicial de clases de diseño de las transmisiones publicadas desde conexiones que utilicen este token.

use OpenTok\Session;
use OpenTok\Role;

// Generate a Token from just a sessionId (fetched from a database)
$token = $opentok->generateToken($sessionId);
// Generate a Token by calling the method on the Session (returned from createSession)
$token = $session->generateToken();

// Set some options in a token
$token = $session->generateToken(array(
    'role'       => Role::MODERATOR,
    'expireTime' => time()+(7 * 24 * 60 * 60), // in one week
    'data'       => 'name=Johnny',
    'initialLayoutClassList' => array('focus')
));

Trabajar con flujos

Puede obtener información sobre un flujo llamando a la función getStream($sessionId, $streamId) método del OpenTok\OpenTok clase.

use OpenTok\Session;

// Get stream info from just a sessionId (fetched from a database)
$stream = $opentok->getStream($sessionId, $streamId);

// Stream properties
$stream->id; // string with the stream ID
$stream->videoType; // string with the video type
$stream->name; // string with the name
$stream->layoutClassList; // array with the layout class list

Puede obtener información sobre todos los flujos de una sesión llamando a la función listStreams($sessionId) método del OpenTok\OpenTok clase.

use OpenTok\Session;

// Get list of streams from just a sessionId (fetched from a database)
$streamList = $opentok->listStreams($sessionId);

$streamList->totalCount(); // total count

Trabajar con archivos

Solo puedes archivar las sesiones que utilicen el OpenTok Media Router (sesiones cuyo modo multimedia esté configurado como «enrutado»).

Puedes iniciar la grabación de una sesión de OpenTok utilizando el startArchive($sessionId, $name) método del OpenTok\OpenTok clase. Esto devolverá un OpenTok\Archive instancia. El parámetro $archiveOptions es una matriz opcional que se utiliza para asignar un nombre, indicar si se va a grabar audio y/o vídeo, el modo de salida deseado para el archivo y la resolución deseada, si procede. Ten en cuenta que solo puedes iniciar un archivo en una sesión que tenga clientes conectados.

// Create a simple archive of a session
$archive = $opentok->startArchive($sessionId);


// Create an archive using custom options
$archiveOptions = array(
    'name' => 'Important Presentation',     // default: null
    'hasAudio' => true,                     // default: true
    'hasVideo' => true,                     // default: true
    'outputMode' => OutputMode::COMPOSED,   // default: OutputMode::COMPOSED
    'resolution' => '1280x720'              // default: '640x480'
);
$archive = $opentok->startArchive($sessionId, $archiveOptions);

// Store this archiveId in the database for later use
$archiveId = $archive->id;

Si configuras el outputMode opción de OutputMode::INDIVIDUALhace que cada secuencia del archivo se grabe en su propio archivo individual. Tenga en cuenta que no puede especificar la resolución cuando configura la opción outputMode opción de OutputMode::INDIVIDUAL. En OutputMode::COMPOSED Esta configuración (la predeterminada) hace que todas las transmisiones del archivo se graben en un único archivo (compuesto).

Tenga en cuenta que también puede crear una sesión archivada automáticamente, pasando en ArchiveMode::ALWAYS como el archiveMode de la options pasado al parámetro OpenTok->createSession() método (véase «Creación de sesiones», más arriba).

Puede detener la grabación de un archivo iniciado mediante la tecla stopArchive($archiveId) método del OpenTok\OpenTok objeto. También puedes hacerlo utilizando el stop() método del OpenTok\Archive instancia.

// Stop an Archive from an archiveId (fetched from database)
$opentok->stopArchive($archiveId);
// Stop an Archive from an Archive instance (returned from startArchive)
$archive->stop();

Para obtener un OpenTok\Archive (y toda su información) a partir de un ID de archivo, utilice la función getArchive($archiveId) método del OpenTok\OpenTok clase.

$archive = $opentok->getArchive($archiveId);

Para eliminar un archivo, puedes llamar a la función deleteArchive($archiveId) método del OpenTok\OpenTok clase o el delete() método de un OpenTok\Archive instancia.

// Delete an Archive from an archiveId (fetched from database)
$opentok->deleteArchive($archiveId);
// Delete an Archive from an Archive instance (returned from startArchive, getArchive)
$archive->delete();

También puede obtener una lista de todos los Archivos que ha creado (hasta 1000) con su Clave API. Para ello utilizando la función listArchives($offset, $count, $sessionId) método del OpenTok/OpenTok clase. Los parámetros $offset, $county $sessionId son opcionales y pueden ayudarte a navegar por los resultados y a filtrar los datos según una sesión concreta. Esto devolverá una instancia de la OpenTok\ArchiveList clase.

$archiveList = $opentok->listArchives();

// Get an array of OpenTok\Archive instances
$archives = $archiveList->getItems();
// Get the total number of Archives for this API Key
$totalCount = $archiveList->totalCount();

En el caso de los archivos compuestos, puede cambiar el diseño dinámicamente, utilizando la función setArchiveLayout($archiveId, $layoutType) método:

use OpenTok\OpenTok;

$layout = Layout::getPIP(); // Or use another get method of the Layout class.
$opentok->setArchiveLayout($archiveId, $layout);

Puedes establecer la clase de diseño inicial para las transmisiones de un cliente configurando el layout cuando al crear el token para el cliente, utilizando la opción OpenTok->generateToken() método o el Session->generateToken() método. Además, puedes modificar las clases de diseño de un flujo llamando al OpenTok->updateStream() método.

La configuración del diseño de los archivos compuestos es opcional. Por defecto, los archivos compuestos utilizan la disposición disposición "más adecuada" (véase Personalización del diseño de vídeo para composiciones archivos).

Para obtener más información sobre el archivado, consulta el Archivado de OpenTok guía del desarrollador.

Trabajar con emisiones

Solo puedes iniciar retransmisiones en directo para las sesiones que utilicen el OpenTok Media Router (sesiones cuyo modo multimedia esté configurado como «routed»).

Inicia la retransmisión en directo de una sesión de OpenTok utilizando el startBroadcast($sessionId, $options) método del OpenTok\OpenTok clase. Esto devolverá un OpenTok\Broadcast Por ejemplo. El $options El parámetro es una matriz que se utiliza para definir las transmisiones y asignar opciones de transmisión como el diseño, la duración máxima, la resolución y otras.

// Define options for the broadcast
$options = [
  'layout' => Layout::getBestFit(),
  'maxDuration' => 5400,
  'resolution' => '1280x720',
  'output' => [
    'hls' => [
      'dvr' => true,
      'lowLatency' => false
    ],
    'rtmp' => [
      [
        'id' => 'foo',
        'serverUrl' => 'rtmps://myfooserver/myfooapp',
        'streamName' => 'myfoostream'
      ],
      [
        'id' => 'bar',
        'serverUrl' => 'rtmps://myfooserver/mybarapp',
        'streamName' => 'mybarstream'
      ],
    ]
  ]
];

// Start a live streaming broadcast of a session
$broadcast = $opentok->startBroadcast($sessionId, $options);

// Store the broadcast ID in the database for later use
$broadcastId = $broadcast->id;

Puedes detener la retransmisión en directo utilizando el stopBroadcast($broadcastId) método del OpenTok\OpenTok objeto. También puedes hacerlo utilizando el stop() método del OpenTok\Broadcast instancia.

// Stop a broadcast from an broadcast ID (fetched from database)
$opentok->stopBroadcast($broadcastId);

// Stop a broadcast from an Broadcast instance (returned from startBroadcast)
$broadcast->stop();

Para obtener un OpenTok\Broadcast instancia (y toda la información relacionada con ella) a partir de un ID de difusión, utiliza el getBroadcast($broadcastId) método del OpenTok\OpenTok clase.

$broadcast = $opentok->getBroadcast($broadcastId);

Puedes modificar el diseño de forma dinámica utilizando el OpenTok->updateBroadcastLayout($broadcastId, $layout) método:

use OpenTok\OpenTok;

$layout = Layout::getPIP(); // Or use another get method of the Layout class.
$opentok->updateBroadcastLayout($broadcastId, $layout);

Puedes utilizar el Layout clase para configurar los tipos de diseño: Layout::getHorizontalPresentation(), Layout::getVerticalPresentation(), Layout::getPIP(), Layout::getBestFit(), Layout::createCustom().

$layoutType = Layout::getHorizontalPresentation();
$opentok->setArchiveLayout($archiveId, $layoutType);

// For custom Layouts, you can do the following
$options = array(
    'stylesheet' => 'stream.instructor {position: absolute; width: 100%;  height:50%;}'
);

$layoutType = Layout::createCustom($options);
$opentok->setArchiveLayout($archiveId, $layoutType);

También puedes configurar el diseño de la pantalla compartida llamando a la función setScreenshareType() método en un objeto de diseño.

$layout = Layout::getBestFit(); // Other types are not currently supported
$layout->setScreenshareType(Layout::LAYOUT_VERTICAL);

Configurar el diseño de las retransmisiones en directo es opcional. Por defecto, las retransmisiones utilizan el diseño «que mejor se adapta» (véase Configuración del diseño de vídeo para las retransmisiones en directo de OpenTok).

Para obtener más información sobre las retransmisiones en directo, consulta la Retransmisiones en directo de OpenTok guía del desarrollador.

Forzar la desconexión de un cliente

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de OpenTok llamando a la función forceDisconnect($sessionId, $connectionId) método del OpenTok\OpenTok clase.

use OpenTok\OpenTok;

// Force disconnect a client connection
$opentok->forceDisconnect($sessionId, $connectionId);

Obligar a los clientes de una sesión a silenciar el audio publicado

Puede forzar al editor de un flujo específico a dejar de publicar audio utilizando la opción Opentok.forceMuteStream($sessionId, $stream) método.

Puede forzar al editor de todos los flujos de una sesión (excepto una lista opcional de flujos) para que deje de publicar audio mediante la opción Opentok.forceMuteAll($sessionId, $excludedStreamIds) método. A continuación, puedes desactivar el estado de silencio de la sesión llamando al Opentok.DisableForceMute(sessionId) o Opentok.DisableForceMuteAsync(sessionId) método.

Envío de señales

Una vez creada una sesión, puedes enviar señales a todos los participantes de la sesión o a una conexión concreta. Puedes enviar una señal llamando a la función signal($sessionId, $payload, $connectionId) método del OpenTok\OpenTok clase.

El $sessionId es el ID de la sesión.

El $payload El parámetro es un array asociativo que se utiliza para configurar lo siguiente:

data (cadena de caracteres) -- La cadena de datos de la señal. Se puede enviar un máximo de 8 kB.
type (cadena) -- — (Opcional) La cadena que identifica el tipo de señal. Se puede enviar un máximo de 128 caracteres, y solo se permiten los siguientes: A-Z, a-z, Numbers (0-9), «-», «_» y «~».

El $connectionId El parámetro es una cadena opcional que se utiliza para especificar el ID de conexión de un cliente conectado a la sesión. Si se especifica este valor, la señal se envía al cliente indicado. De lo contrario, la señal se envía a todos los clientes conectados a la sesión.

use OpenTok\OpenTok;

// Send a signal to a specific client
$signalPayload = array(
    'data' => 'some signal message',
    'type' => 'signal type'
);
$connectionId = 'da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf';
$opentok->signal($sessionId, $signalPayload, $connectionId);

// Send a signal to everyone in the session
$signalPayload = array(
    'data' => 'some signal message',
    'type' => 'signal type'
);
$opentok->signal($sessionId, $signalPayload);

Para más información, consulte el Guía para desarrolladores de señalización de OpenTok.

Trabajar con la interconexión SIP

Puedes añadir un flujo de solo audio procedente de una pasarela SIP externa de terceros mediante la función de interconexión SIP. Para ello, se necesita un URI SIP, el ID de sesión al que deseas añadir el flujo de solo audio y un token para conectarte a ese ID de sesión.

Para iniciar una llamada SIP, llama al dial($sessionId, $token, $sipUri, $options) método del OpenTok\OpenTok clase:

$sipUri = 'sip:user@sip.partner.com;transport=tls';

$options = array(
  'headers' =>  array(
    'X-CUSTOM-HEADER' => 'headerValue'
  ),
  'auth' => array(
    'username' => 'username',
    'password' => 'password'
  ),
  'secure' => true,
  'from' => 'from@example.com'
);

$opentok->dial($sessionId, $token, $sipUri, $options);

Para más información, consulte el Guía para desarrolladores de OpenTok SIP Interconnect.

Cómo trabajar con Audio Connector

Puedes iniciar un Conector de audio WebSocket mediante la llamada a la función connectAudio() método del OpenTok\OpenTok clase.

Requisitos

Necesitas una clave API y un secreto API de OpenTok, que puedes obtener iniciando sesión en tu Cuenta API de Video de Vonage.

El SDK de OpenTok para PHP requiere PHP 7.2 o una versión superior.

Notas de publicación

Véase el Comunicados para más detalles.

Cambios importantes desde la versión 2.2.0

Cambios en la versión 2.2.1:

La configuración predeterminada para el createSession() El método consiste en crear una sesión con el modo multimedia configurado en «relayed». En versiones anteriores del SDK, la configuración predeterminada era utilizar el OpenTok Media Router (modo multimedia configurado en «routed»). En una sesión de retransmisión, los clientes intentarán enviar flujos directamente entre ellos (punto a punto); si los clientes no pueden conectarse debido a restricciones del cortafuegos, la sesión utiliza el servidor TURN de OpenTok para retransmitir los flujos de audio y vídeo.

Cambios en la versión 2.2.0:

Esta versión del SDK incluye compatibilidad para trabajar con archivos de OpenTok.

Los nombres de muchos métodos de la API han cambiado. Muchos nombres de métodos han cambiado para utilizar el formato «camel case», entre ellos los siguientes:

\OpenTok\OpenTok->createSession()
\OpenTok\OpenTok->generateToken()

Ten en cuenta también que el options del OpenTok->createSession() El método tiene un mediaMode propiedad en lugar de un p2p propiedad.

Se ha eliminado la clase API_Config. Guarda tu clave API y tu secreto API de OpenTok en el código, fuera de los archivos del SDK.