Skip to end of metadata
Go to start of metadata

Описание

WCS позволяет микшировать потоки активных трансляций. Выходной поток микшера может быть записан, воспроизведен или ретранслирован по любой из технологий, поддерживаемых WCS.

Микширование управляется при помощи настроек и REST API.

Поддерживаемые протоколы входных потоков

  • WebRTC
  • RTMP
  • RTSP

Возможности управления выходным потоком

Микшер позволяет задать размещение видеопотоков в выходном кадре. Поток с определенным именем (по умолчанию desktop) рассматривается, как демонстрация экрана (screen sharing), и размещается в центре кадра:

Автоматическое создание микшера при публикации потока

Если в имени публикуемого RTMP-потока есть символ '#', сервер рассматривает все, что после данного символа, как имя микшера, который будет создан автоматически при публикации потока. Например, для потока user1#room1 будет создан микшер room1, и поток будет в этот микшер добавлен. В имени потока может быть указано и ключевое слово демонстрации экрана, например user1#room1#desktop

Схема работы

  1. Браузер соединяется с сервером по протоколу Websocket и отправляет команду publish.
  2. Браузер отправляет WebRTC поток stream1 на сервер.
  3. Flash Player устанавливает соединение по RTMP и отправляет команду publish.
  4. Flash Player отправляет RTMP поток stream2 на сервер.
  5. REST-клиент создает микшер с выходным потоком stream3 запросом /mixer/startup
  6. REST-клиент добавляет к микшеру поток stream1
  7. REST-клиент добавляет к микшеру поток stream2
  8. Второй браузер устанавливает соединение по Websocket и отправляет команду play.
  9. Второй браузер получает WebRTC аудиопоток stream3 и воспроизводит этот поток на странице.

REST-вызовы

REST-запрос должен быть HTTP/HTTPS POST запросом в таком виде:

Здесь:

  • streaming.flashphoner.com - адрес WCS-сервера
  • 8081 - стандартный REST / HTTP порт WCS-сервера
  • 8444 - стандартный HTTPS порт
  • rest-api - обязательный префикс
  • mixer/startup - используемый REST-вызов

REST-вызовы и статусы ответа

REST-метод

Пример тела REST-запроса

Пример ответа

Статусы ответа

Описание

/mixer/startup

{
 "uri": "mixer://mixer1",
 "localStreamName": "stream3",
 "hasVideo": "true",
 "hasAudio": "true",
 "watermark": "watermark.png",
 "background": "background.png",
 "mixerLayoutClass": "com.flashphoner.mixerlayout.TestLayout"
}

200 - OK

409 - Conflict

500 - Internal error

Создает микшер, для которого публикуется поток с указанным именем

/mixer/add

{
 "uri": "mixer://mixer1",
 "remoteStreamName": "stream1",
 "hasVideo": "true",
 "hasAudio": "true"
}

200 - OK

404 - Mixer not found

404 - Stream not found

500 - Internal error

Добавить RTMP-поток в микшер

/mixer/remove

{
 "uri": "mixer://mixer1",
 "remoteStreamName": "stream1"
}

200 - OK

404 - Mixer not found

404 - Stream not found

500 - Internal error

Убрать RTMP-поток из микшера

/mixer/find_all


{
"localMediaSessionId": "ce92b134-2468-4460-8d06-1ea3c5aabace",
"remoteMediaSessionId": null,
"localStreamName": "mixer1",
"remoteStreamName": null,
"uri": "mixer://mixer1",
"status": "PROCESSED_LOCAL",
"mediaSessions": [
 "95bf2be8-f459-4f62-9a7f-c588f33e0ad3",
 "693781de-cada-4589-abe1-c3ee55c66901"
]
}

200 - OK

404 - Not found

500 - Internal error

Найти все микшеры

/mixer/terminate

{
 "uri": "mixer://mixer1"
}

200 - OK

404 - Not found

500 - Internal error

Завершить работу микшера

/stream/startRecording

{
 "mediaSessionId": "23d07fa1-3c74-4d6f-a0de-9b4bf83ce665"
}

200 - OK

404 - Not found

500 - Internal error

Начать запись потока в указанной медиасессии

/stream/stopRecording

{
 "mediaSessionId": "23d07fa1-3c74-4d6f-a0de-9b4bf83ce665"
}

200 - OK

404 - Not found

500 - Internal error

Завершить запись потока в указанной медиасессии

Параметры

Имя параметра

Описание

Пример

uri

Уникальный идентификатор микшера

mixer://mixer1

localStreamName

Имя выходного потока микшера

stream3

hasVideoМикшировать видеоtrue
hasAudioМикшировать аудиоtrue

remoteStreamName

Имя потока, добавляемого в микшер

stream1

rtmp://rtmp.flashphoner.com:1935/live/rtmp_stream1

mediaSessionId

Идентификатор медиасессии

ce92b134-2468-4460-8d06-1ea3c5aabace

status

Статус потока

PROCESSED_LOCAL

backgroundФоновое изображениеbackground.png
watermarkВодяной знакwatermark.png
mixerLayoutClassКласс размещения картинок в потокеcom.flashphoner.mixerlayout.TestLayout

Отправка REST-запроса к WCS-серверу

Для отправки REST-запроса к WCS-серверу необходимо использовать REST-клиент.

Настройка

Основные настройки микширования задаются при помощи следующих параметров файла настроек flashphoner.properties

Параметр

Значение по умолчанию

Описание

mixer_video_desktop_layout_inline_padding

10

Расстояние между окнами видеопотоков в нижней строке (под окном демонстрации экрана)

mixer_video_desktop_layout_padding

30

Расстояние между окном видеопотока демонстрации экрана и нижней строкой (остальные видеопотоки)

mixer_video_enabled

true

Включает (по умолчанию) или отключает микширование видео

mixer_video_grid_layout_middle_padding

10

Расстояние между окнами видеопотоков в одной строке (при отсутствии демонстрации экрана)

mixer_video_grid_layout_padding

30

Расстояние между строками видеопотоков (при отсутствии демонстрации экрана)

mixer_video_height

720

Высота изображения выходного потока микшера, значение должно быть четным. Нечетное значение будет автоматически уменьшено на единицу: например, при 481 высота микшера будет 480.

mixer_video_layout_desktop_key_word

desktop

Ключевое слово для потока демонстрации экрана (screen sharing)

mixer_video_width

1280

Ширина изображения выходного потока микшера, значение должно быть четным. Нечетное значение будет автоматически уменьшено на единицу: например, при 641 ширина микшера будет 640.

record_mixer_streams

false

Включает или отключает (по умолчанию) запись всех выходных потоков микшера

Настройка автоматического создания микшера при публикации потока

Для того, чтобы включить возможность автоматического создания микшера для потоков, содержащих в имени символ '#', необходимо, чтобы приложение, которое обрабатывает входящие потоки, зарегистрировало обработчик 'com.flashphoner.server.client.handler.wcs4.FlashRoomRecordingStreamingHandler'. Регистрация обработчика производится при помощи интерфейса командной строки. Например, для приложения flashStreamingApp, используемого для публикации входящих RTMP потоков, это делается командой

update app -m com.flashphoner.server.client.handler.wcs4.FlashRoomRecordingStreamingHandler -c com.flashphoner.server.client.handler.wcs4.FlashStreamingCallbackHandler flashStreamingApp

Подробнее об управлении приложениями из командной строки WCS-сервера можно узнать здесь.

Настройка микширования аудио и видео

По умолчанию микшируются видео и аудиопотоки. Если необходимо микшировать только аудио, необходимо указать это при создании микшера

{
 "uri": "mixer://mixer1",
 "localStreamName": "stream3",
 "hasVideo": "false"
}

Если необходимо отключить микширование видео для всех потоков, необходимо указать параметр в файле flashphoner.properties

mixer_video_enabled=false

При этом видео может быть включено для определенного микшера при его создании.

В сборке 5.2.689 добавлена возможность включить или отключить микширование аудио при создании микшера

{
 "uri": "mixer://mixer1",
 "localStreamName": "stream3",
 "hasAudio": "false"
}

или в настройках сервера для всех потоков

mixer_audio_enabled=false

Буферизация выходного потока микшера

В некоторых случаях необходима буферизация выходного потока микшера. Эта функция включается настройкой в файле flashphoner.properties

mixer_out_buffer_enabled=true

Размер буфера задается в миллисекундах настройкой

mixer_out_buffer_start_size=400

В данном случае размер буфера составит 400 мс.

Период отправки данных потока из буфера в миллисекундах указывается настройкой

mixer_out_buffer_polling_time=20

В данном случае период составляет 20 мс.

Управление битрейтом выходного потока микшера

Если в качестве транскодера используется кодек OpenH264, появляется возможность управлять битрейтом выходного потока микшера при помощи настройки в файле flashphoner.properties

mixer_video_bitrate_kbps=2000

По умолчанию, битрейт выходного потока установлен в 2 Мбит/с. При недостаточной пропускной способности канала между сервером и зрителем битрейт может быть понижен, например

encoder_priority=OPENH264
mixer_video_bitrate_kbps=1500

Если качество картинки с битрейтом по умолчанию низкое, присутствуют искажения, рекомендуется увеличить битрейт выходного потока микшера до 3-5 Мбит/с

encoder_priority=OPENH264
mixer_video_bitrate_kbps=5000

Управление звуковой дорожкой выходного потока микшера

По умолчанию, звуковая дорожка в выходном потоке микшера кодируется в Opus с частотой дискретизации 48 кГц. Эти параметры могут быть изменены при помощи настроек в файле flashphoner.properties. Например, для использования выходного потока в SIP, можно установить следующие значения:

audio_mixer_output_codec=pcma
audio_mixer_output_sample_rate=8000

В этом случае звук будет кодироваться в PCMA (alaw) с частотой дискретизации 8 кГц.

Собственный lossless видеопроцессор для входящих потоков

Для обработки входящих потоков микшера, например, если необходима дополнительная буферизация или синхронизация аудио и видео дорожек, может быть использован собственный lossless видеопроцессор. Этот видеопроцессор включается настройкой в файле flashphoner.properties

mixer_lossless_video_processor_enabled=true

Максимальный размер буфера микшера в миллисекундах устанавливается настройкой

mixer_lossless_video_processor_max_mixer_buffer_size_ms=200

По умолчанию, размер буфера микшера составляет 200 мс. При его заполнении, видеопроцессор использует свой собственный буфер и ожидает освобождения буфера микшера. Периодичность проверки буфера микшера устанавливается в миллисекундах настройкой

mixer_lossless_video_processor_wait_time_ms=20

По умолчанию, периодичность проверки составляет 20 мс.

Необходимо отметить, что использование lossless видеопроцессора может вносить задержку в трансляции в реальном времени.

При использовании lossless видеопроцессора, чтобы освободить ресурсы, занятые микшером, нужно принудительно остановить микшер при помощи REST запроса /mixer/terminate, либо остановить все входящие в микшер потоки, в этом случае микшер остановится по истечении времени, заданного в миллисекундах настройкой

mixer_idle_timeout=60000

По умолчанию, при отсутствии входящих потоков, микшер останавливается через 60 секунд.

Управление размещением картинок в выходном потоке микшера

По умолчанию, микшер предусматривает три варианта размещения картинок входных потоков в выходном потоке:

Картинки сеткой

Этот вариант включается настройкой в файле flashphoner.properties

mixer_layout_class=com.flashphoner.media.mixer.video.presentation.GridLayout

Картинки сеткой с минимальным расстоянием между ними

Этот вариант включается настройкой

mixer_layout_class=com.flashphoner.media.mixer.video.presentation.CenterNoPaddingGridLayout

и обеспечивается только для входных потоков одинакового разрешения, с одинаковым соотношением сторон

Демонстрация экрана (screen sharing)

Этот вариант включается, если на вход микшеру подается поток с именем, указанным в настройке

mixer_video_layout_desktop_key_word=desktop

По умолчанию, для потока демонстрации экрана используется имя desktop.

В сборке 5.2.710 добавлена возможность настройки размещения картинки экрана (screen sharing):

mixer_desktop_align=TOP

По умолчанию, картинка экрана размещается над остальными картинками

Поддерживаются следующие варианты размещения:

ВариантОписание
TOPЭкран вверху
LEFTЭкран слева
RIGHTЭкран справа
BOTTOMЭкран внизу
CENTERЭкран в центре (картинки потоков вокруг)

Например, при настройке

mixer_desktop_align=RIGHT

экран будет помещен справа от остальных картинок

Если опубликовано несколько потоков с экрана, главным потоком будет выбран тот, который опубликован первым. Если затем этот поток будет завершен, его место займет поток, следующий по алфавиту.

Реализация собственного варианта размещения картинок

Для более тонкой настройки размещения картинок в выходном потоке микшера необходимо разработать класс на языке Java, реализующий интерфейс IVideoMixerLayout, например

TestLayout.java
// Package name should be strictly defined as com.flashphoner.mixerlayout
package com.flashphoner.mixerlayout;

// Import mixer layout interface
import com.flashphoner.sdk.media.IVideoMixerLayout;
// Import YUV frame description
import com.flashphoner.sdk.media.YUVFrame;

// Import Java packages to use
import java.awt.*;
import java.util.ArrayList;

/**
 * Custom mixer layout implementation example
 */
public class TestLayout implements IVideoMixerLayout {

    // Pictures padding, should be even (or zero if no padding needed)
    private static final int PADDING = 4;

    /**
     * Function to compute layout, will be called by mixer before encoding output stream picture
     * This example computes grid layout
     * @param yuvFrames - incoming streams raw pictures array in YUV format
     * @param strings - incoming streams names array
     * @param canvasWidth - mixer output picture canwas width
     * @param canvasHeight - mixer output picture canwas heigth
     * @return array of pictures layouts
     */
    @Override
    public Layout[] computeLayout(YUVFrame[] yuvFrames, String[] strings, int canvasWidth, int canvasHeight) {
        // Declare picture layouts list to fill
        ArrayList<IVideoMixerLayout.Layout> layout = new ArrayList<>();

        // Find canvas center height
        int canvasCenter = canvasHeight / 2;
        // Find frame center
        int frameCenter = canvasCenter - (canvasHeight / yuvFrames.length) / 2;

        // Find every picture dimensions (this are the same for all the pictures because this is grid layout)
        int layoutWidth = canvasWidth / yuvFrames.length - PADDING;
        int layoutHeight = canvasHeight / yuvFrames.length;

        // Iterate through incoming stream pictures array
        // Note: streams pictures order corresponds to stream names array, use this to reorder pictures if needed
        for (int c = 0; c < yuvFrames.length; c++) {
            // Use Java AWT Point and Dimension
            Point prevPoint = new Point();
            Dimension prevDimension = new Dimension();
            if (layout.size() > 0) {
                // Find previous picture location to calculate next one
                prevPoint.setLocation(layout.get(c - 1).getPoint());
                prevDimension.setSize(layout.get(c - 1).getDimension());
            }
            // Set starting point of the picture
            Point currentPoint = new Point((int) (prevPoint.getX() + prevDimension.getWidth() + PADDING),
                    frameCenter);
            // Create the picture layout passing starting point, dimensions and raw picture YUV frames
            layout.add(new IVideoMixerLayout.Layout(currentPoint, new Dimension(layoutWidth,
                    layoutHeight), yuvFrames[c]));
        }
        // Return pictures layouts calculated as array
        return layout.toArray(new IVideoMixerLayout.Layout[layout.size()]);
    }
}

Затем следует скомпилировать класс в байт-код. Для этого создаем дерево каталогов, соответствующее названию пакета написанного класса

mkdir -p com/flashphoner/mixerlayout

и выполняем команду

javac -cp /usr/local/FlashphonerWebCallServer/lib/wcs-core.jar ./com/flashphoner/mixerlayout/TestLayout.java

Теперь упакуем скомпилированный код в jar-файл

jar -cf testlayout.jar ./com/flashphoner/mixerlayout/TestLayout.class

и скопируем его в каталог, где размещены библиотеки WCS сервера

cp testlayout.jar /usr/local/FlashphonerWebCallServer/lib

Для того, чтобы использовать разработанный класс, необходимо указать его в настройке в файле flashphoner.properties

mixer_layout_class=com.flashphoner.mixerlayout.TestLayout

и перезапустить WCS.

Выходной поток микшера для приведенного примера и трех входящих потоков будет выглядеть так:

Управление размещением картинок при создании микшера

В сборке 5.2.693 появилась возможность указать размещение картинок при создании микшера по REST API, например

{
 "uri": "mixer://mixer1",
 "localStreamName": "mixer1",
 "mixerLayoutClass": "com.flashphoner.mixerlayout.TestLayout"
}

Таким образом, размещением картинок можно управлять для каждого микшера отдельно

Управление профилем кодирования выходного потока микшера

Некоторые браузеры не поддерживают воспроизведение H264 потока, закодированного с определенным профилем. В связи с этим, в сборке 5.2.414 добавлена настройка для указания профиля кодирования выходного потока микшера

mixer_video_profile_level=42c02a

По умолчанию, задан профиль constrainted baseline level 4.2.

Управление фоном микшера и добавление водяного знака

В сборке 5.2.693 появилась возможность указать фон микшера и добавить водяной знак при создании микшера по REST API, например

{
 "uri": "mixer://mixer1",
 "localStreamName": "mixer1",
 "watermark": "watermark.png",
 "background": "background.png"
}

По умолчанию, файлы должны располагаться в каталоге /usr/local/FlashphonerWebCallServer/conf. Можно указать и полный путь к файлам, например

{
 "uri": "mixer://mixer1",
 "localStreamName": "mixer1",
 "watermark": "/opt/media/watermark.png",
 "background": "/opt/media/background.png"
}

Поддержка MCU

Поддержка MCU в микшере включается для аудио настройкой

mixer_mcu_audio=true

В этом случае для трех входящих потоков stream1, stream2, stream3 на выходе микшера mixer1 будут следующие потоки:

Output stream namestream1 stream2stream3
audiovideoaudiovideoaudiovideo
mixer1++++++
mixer1-stream1--+-+-
mixer1-stream2+---+-
mixer1-stream3+-+---

Таким образом, каждый из дополнительных потоков содержит аудио всех потоков в микшере, кроме одного. Это позволяет, например, устранить эхо для участников конференции.

Аналогичная возможность для видео включается настройкой

mixer_mcu_video=true

В этом случае для трех входящих потоков stream1, stream2, stream3 на выходе микшера mixer1 будут следующие потоки:

Output stream namestream1 stream2stream3
audiovideoaudiovideoaudiovideo
mixer1++++++
mixer1-stream1--++++
mixer1-stream2++--++
mixer1-stream3++++--

Таким образом, каждый из дополнительных потоков содержит аудио и видео всех потоков в микшере, кроме одного. Это позволяет организовать полноценную чат-комнату на базе микшера.

При этом, если включена запись микшера при помощи настройки

record_mixer_streams=true

будет записываться только основной выходной поток микшера (mixer1 в вышеприведенном примере).

При включении MCU для видео, потери на канале могут сказываться на качестве выходного потока микшера. Для улучшения качества видео может быть использован собственный lossless видеопроцессор, что, в свою очередь, может внести дополнительную задержку.

Краткое руководство по тестированию

1. Для теста используем:

  • демо-сервер demo.flashphoner.com;
  • браузер Chrome и REST-клиент для отправки запросов на сервер;
  • веб-приложение Two Way Streaming для публикации входных потоков микшера;
  • веб-приложение Player для воспроизведения выходного потока микшера.

2. Откройте страницу веб-приложения Two Way Streaming. Опубликуйте поток с именем stream1:

 


3. В другой вкладке откройте страницу веб-приложения Two Way Streaming. Опубликуйте поток с именем desktop:

 


 4. Откройте REST-клиент. Отправьте запрос /mixer/startup, указав в параметрах URI микшера mixer://mixer1 и имя выходного потока stream3:

 


 5. Отправьте запрос /mixer/add, указав в параметрах URI микшера mixer://mixer1 и имя входного потока stream1:

 


 6. Откройте веб-приложение Player, укажите в поле Stream имя выходного потока микшера stream3 и нажмите Start:

 


 7. Отправьте запрос /mixer/add, указав в параметрах URI микшера mixer://mixer1 и имя входного потока desktop:

 


 8. В выходном потоке микшера отобразится поток desktop, имитирующий демонстрацию экрана, и поток stream1:

 

Последовательность выполнения операций (Call flow)

Ниже описана последовательность вызовов при использовании микшера.


1. Публикация WebRTC-потока stream1

2. Отправка RTMP-потока на сервер

3. Публикация RTMP-потока stream2

4. Отправка RTMP-потока на сервер

5. Отправка запроса /mixer/startup на создание микшера mixer://stream3 с выходным потоком stream3

http://demo.flashphoner.com:9091/rest-api/mixer/startup
{
 "uri": "mixer://stream3",
 "localStreamName": "stream3"
}


6. Отправка запроса /mixer/add на добавление к микшеру mixer://stream3 потока stream1

http://demo.flashphoner.com:9091/rest-api/mixer/add
{
 "uri": "mixer://stream3",
 "localStreamName": "stream3"
 "remoteStreamName": "stream1"
}


7. Отправка запроса /mixer/add на добавление к микшеру mixer://stream3 потока stream2

http://demo.flashphoner.com:9091/rest-api/mixer/add
{
 "uri": "mixer://stream3",
 "localStreamName": "stream3"
 "remoteStreamName": "stream2"
}


8. Воспроизведение WebRTC-потока stream3

9. Отправка WebRTC-аудиопотока клиенту

REST hooks для микшера

По умолчанию, для выходного потока микшера могут быть обработаны все стандартные REST методы. При этом, метод /connect приходит на бэкенд сервер при создании микшера.

При необходимости, для микшера может быть создано отдельное REST-приложение. Чтобы направить вызовы от микшера к этому приложению, в сборке 5.2.634 добавлена настройка

mixer_app_name=defaultApp

По умолчанию, вызовы от микшера обрабатывает приложение defaultApp, как и для остальных потоков.

Известные проблемы

1. Микшер не создается, если имя микшера или имя выходного потока содержит символы, недопустимые для указания в URI

Симптомы: не создается микшер с именем вида test_mixer.

Решение: не использовать в имени микшера или имени выходного потока недопустимые символы, в особенности, если включена возможность автоматичекого создания микшера. Например, имя

user_1#my_room

использовать нельзя.

Если микшируются потоки чат-комнат, в именах комнат также нельзя использовать недопустимые символы.

2. Выходной поток микшера будет пустым, если на сервере включен транскодинг только по требованию.

Симптомы: микшер видеопотоков успешно создается, но в выходном потоке черный экран.

Решение: для работы микшера на сервере должен быть включен транскодинг при помощи следующего параметра в файле flashphoner.properties

streaming_video_decoder_fast_start=true

3. Один поток не может быть добавлен в два микшера одновременно

Симптомы: при добавлении потока во второй микшер выходной поток первого микшера останавливается

Решение: не использовать один поток более чем в одном микшере