gst-launch-1.0 - построение и запуск конвейера мультимедийной обработки (GStreamer pipeline).
SYNOPSIS
gst-launch-1.0 [OPTION...] PIPELINE-DESCRIPTION
ОПИСАНИЕ
gst-launch-1.0 это инструмент для сборки и запуска базовых контейнеров GStreamer.
В простой форме PIPELINE-DESCRIPTION представляет список элементов, отделенных друг от друга символом восклицательного знака (!). К элементам могут быть добавлены свойства в форме property=value (так называемый "preset"). Preset может быть также установлен с помощью синтаксиса @preset=< preset name>.
Для полного описания возможных PIPELINE-DESCRIPTIONS см. далее секцию описания конвейера (pipeline), или проконсультируйтесь с документацией GStreamer [1].
Обратите внимание, что gst-launch-1.0 это в основном инструмент отладки для разработчиков и пользователей. Вам не следует строить на его основе приложения. Для приложений используйте функцию gst_parse_launch() GStreamer API как простой способ конструирования конвейеров из их описаний.
ОПЦИИ
gst-launch-1.0 принимает следующие опции:
--help Выведет краткое изложение справки по опциям и доступных FLAGS командной строки.
-v, --verbose Выведет информацию статуса и оповещений свойств.
-q, --quiet Не печатать никакую информацию о процессе обработки.
-m, --messages Выведет сообщения, которые были опубликованы на шине конвейера.
-t, --tags Выведет теги, также известные как метаданные файла (metadata).
-e, --eos-on-shutdown Принудительно выполнит событие EOS для источников перед закрытием конвейера. Это полезно, чтобы убедиться, что мультиплексоры (muxers) создают читаемые файлы, когда мультиплексирующий конвейер (muxing pipeline) принудительно отключается через Control-C.
-i, --index Захватывает и печатает статистику индекса. Это в основном полезно для конвейеров воспроизведения (playback pipeline) или записи (recording pipeline).
-f, --no-fault Не инсталлировать обработчик отказа (fault handler).
-T, --trace Печатает трассировку выделений памяти. Чтобы эта фича работала, её надо разрешить в момент компиляции.
--no-position Не печатать текущее положение конвейера. Если этот параметр не указан, то позиция будет распечатана, когда stdout это TTY. Чтобы включить положение печати, когда stdout не является TTY, используйте опцию "force-position".
--force-position Позволяет печатать текущую позицию конвейера даже когда stdout не TTY. Эта опция не дает эффекта, если указана опция "no-position".
ОПЦИИ GSTREAMER
gst-launch-1.0 также принимает следующие опции, которые являются общими для всех приложений GStreamer:
--gst-version Печатает строку версии основной библиотеки GStreamer.
--gst-fatal-warnings Приводит к тому, что GStreamer аварийно прерывает работу (abort), если появилось сообщение предупреждения (warning message). Это эквивалентно установке переменной окружения G_DEBUG в 'fatal_warnings' (для дополнительной информации см. далее секцию описания переменных окружения).
--gst-debug=STRING Список с разделителем запятой пар category_name:level, чтобы указать уровни отладки для каждой категории. Здесь уровень level устанавливается в диапазоне 0-9, где 0 не будет выдавать сообщений, а 9 будет показывать все сообщения. Может использоваться шаблон wildcard * для совпадения с несколькими именами категорий. Обратите внимание, что порядок следования категорий и уровни важны, так что wildcard, установленные в конце списка, могут отменить действия установок, заданных ранее. Уровни лога следующие: 1=ERROR, 2=WARNING, 3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE, 9=MEMDUMP. Начиная с версии GStreamer 1.2 можно также использовать имена уровней отладки, например --gst-debug=*sink:LOG. Полное описание различных уровней отладки можно найти в документации GStreamer core library API documentation, см. секцию "Running GStreamer Applications".
Используйте --gst-debug-help, чтобы показать имена категорий. Пример: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
--gst-debug-level=LEVEL Установит порог печати отладочных сообщений. Более высокий уровень будет печатать больше сообщений. Используемый диапазон уровня 0-9, по умолчанию используется 0. Уровень 6 (уровень LOGl) покажет всю информацию, которая обычно требуется для отладки. Более высокие уровни полезны только в особых случаях. См. выше полный список уровней.
--gst-debug-no-color GStreamer нормально печатает сообщения отладки таким образом, что текст сообщений раскрашивается с помощью последовательностей управляющих кодов (ANSI escape sequences). Использование этой опции заставляет GStreamer печатать монохромные сообщения. Установка переменной окружения GST_DEBUG_NO_COLOR дает такой же эффект.
--gst-debug-color-mode GStreamer обычно печатает цветные отладочные сообщения, когда используется терминал с поддержкой обработки ANSI escape sequences (что обычно верно на *nix), или использует W32 console API для раскраски сообщений, печатаемых в консоль (на W32). Использование этой опции заставит GStreamer печатать сообщения без цвета ('off' или 'disable'), печатать сообщения с подкрашиванием по умолчанию ('on' или 'auto'), или печатать сообщения, используя ANSI escape sequences для раскрашивания текста ('unix'). Установка переменной окружения GST_DEBUG_COLOR_MODE дает тот же эффект.
--gst-debug-disable Запрет отладки.
--gst-debug-help Печатает список доступных категорий отладки и их уровень отладки по умолчанию.
--gst-plugin-path=PATH Добавляет директории, разделенные символом ':', в путь поиска плагинов.
--gst-plugin-load=PLUGINS Предварительно загружает плагины, указанные в списке с разделителем запятой. Другой способ указать предварительно загружаемые плагины - использование переменной окружения GST_PLUGIN_PATH.
PIPELINE DESCRIPTION (описание конвейера)
Конвейер состоит из элементов (element) и линков (links). Элементы могут быть помещены в различные ячейки: бины (bins). Элементы, линки и бины могут быть указаны в описании конвейера в любом порядке.
Элементы
ELEMENTTYPE [PROPERTY1 ...]
Создаст элемент типа ELEMENTTYPE и установит его свойства (PROPERTY).
Свойства
PROPERTY=VALUE ...
Установит свойству указанное значение. Вы можете использовать gst-inspect-1.0(1), чтобы найти информацию о свойствах и разрешенных значениях различных элементов. Перечисление свойств может быть установлено по имени (name), нику (nick) или значению (value).
Пресеты
@preset=< preset name> ...
Установит пресет на элементе. Вы можете использовать gst-inspect-1.0(1), чтобы найти информацию о пресетах, доступных для определенного элемента.
Бины (bins)
[BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
Указывает, что создается бин типа BINTYPE, и устанавливается в нем указанные свойства. Каждый элемент внутри круглых скобок помещается в бин. Обратите внимание, что после BINTYPE должна использоваться точка. Функционал бинов вам почти никогда не понадобится, он действительно полезен только для приложений, использующих gst_launch_parse() API с 'bin' в качестве bintype. Таким образом, можно построить части конвейера вместо полноценного конвейера верхнего уровня.
Линки (links)
[[SRCELEMENT].[PAD1,...]] !
[[SINKELEMENT].[PAD1,...]] [[SRCELEMENT].[PAD1,...]] !
CAPS !
[[SINKELEMENT].[PAD1,...]] [[SRCELEMENT].[PAD1,...]] :
[[SINKELEMENT].[PAD1,...]] [[SRCELEMENT].[PAD1,...]] :
CAPS : [[SINKELEMENT].[PAD1,...]]
Линки связывают элемент с именем SRCELEMENT с элементом с именем SINKELEMENT, используя в качестве фильтра caps, указанные в CAPS. Имена могут быть заданы для элементов со свойством name. Если имя опущено, то используется элемент, указанный непосредственно перед или после ссылки. Это работает через бины. Если указано padname, связь выполняется с этими падами. Если имена падов не даны, то пробуются все возможности и используется соответствующий пад. Если задано несколько имен, обе стороны должны иметь одинаковое количество указанных падов, и несколько линков выполняются в заданном порядке. Таким образом, самый простой линк - простой восклицательный знак, который связывает элемент слева от него с элементом справа от него. Оператор : пытается связать все возможные пады между элементами.
Caps
MEDIATYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
Создает возможность с заданным типом носителя и, при необходимости, с заданными свойствами. Тип носителя можно экранировать с помощью " или '. Если вы хотите цепочку caps, то можете добавить впоследствии больше caps в том же формате.
Properties (свойства)
NAME=[(TYPE)]VALUE в списках и диапазонах: [(TYPE)]VALUE
Установит запрошенное свойство в возможностях (capabilities). Имя это алфавитно-цифровое значение, и тип может иметь следующие значения, не чувствительные к регистру символов (case-insensitive):
- i или int для целочисленных значений или диапазонов
- f или float для значений с плавающей запятой или диапазонов
- b, bool или boolean для двоичных значений
- s, str или string для строк
- fraction для дробей (частота кадров framerate, соотношение пикселей и сторон pixel-aspect-ratio)
- l или list для списков
Если тип не был указан, то делается попытка применить тип в следующем порядке: integer, float, boolean, string. Целочисленные значения должны быть такие, которые анализируются через strtol(), а значения с плавающей запятой должны анализироваться strtod(). Значения FOURCC могут быть либо int, либо string. Значения boolean (не чувствительные к регистру) это yes, no, true или false, и они как и строки могут экранироваться через " или '.
Диапазоны (ranges) задаются в формате: [ VALUE, VALUE ]
Списки используют формат: { VALUE [, VALUE ...] }
ПРИМЕРЫ КОНВЕЙЕРОВ
Примеры, приведенные ниже, подразумевает доступность у вас корректных плагинов. В общем, "pulsesink" может быть заменен на другой плагин вывода звука (audio output plug-in), таким как "alsasink" или "osxaudiosink". Подобным образом "xvimagesink" может быть заменен на "ximagesink", "glimagesink", или "osxvideosink". Имейте в виду, что различные сливы данных (sinks) могут принимать различные форматы, и даже один и тот же sink может принимать на разных машинах разные форматы. Так что вам нужно добавить элементы преобразования наподобие audioconvert и audioresample (для звука audio) или videoconvert (для video) перед sink, чтобы он смог работать.
Audio playback (воспроизведение звука)
Проиграет музыкальный файл "music.mp3" формата mp3, используя libmpg123-based плагин, и выведет его на устройство Pulseaudio:
gst-launch-1.0 filesrc location=music.mp3 ! mpegaudioparse !
mpg123audiodec ! audioconvert ! audioresample ! pulsesink
Проиграет файл формата Ogg Vorbis:
gst-launch-1.0 filesrc location=music.ogg ! oggdemux ! vorbisdec !
audioconvert ! audioresample ! pulsesink
Проиграет файл mp3 или поток http, используя GIO:
gst-launch-1.0 giosrc location=music.mp3 ! mpegaudioparse !
mpg123audiodec ! audioconvert ! pulsesink
gst-launch-1.0 giosrc location=http://domain.com/music.mp3 !
mpegaudioparse ! mpg123audiodec ! audioconvert ! audioresample !
pulsesink
Использование GIO для проигрывания файла mp3, размещенного на сервере SMB:
gst-launch-1.0 giosrc location=smb://computer/music.mp3 ! mpegaudioparse !
mpg123audiodec ! audioconvert ! audioresample ! pulsesink
Преобразование формата
Преобразует музыкальный файл mp3 в файл Ogg Vorbis:
gst-launch-1.0 filesrc location=music.mp3 ! mpegaudioparse !
mpg123audiodec ! audioconvert ! vorbisenc ! oggmux !
filesink location=music.ogg
Преобразование в формат FLAC:
gst-launch-1.0 filesrc location=music.mp3 ! mpegaudioparse !
mpg123audiodec ! audioconvert ! flacenc ! filesink location=test.flac
Другое
Проиграет файл .WAV, который содержит данные сырых выборок звука (raw audio data) PCM.
gst-launch-1.0 filesrc location=music.wav ! wavparse ! audioconvert !
audioresample ! pulsesink
Преобразует файл .WAV, содержащий сырые данные звука в файл формата Ogg Vorbis или mp3:
gst-launch-1.0 filesrc location=music.wav ! wavparse ! audioconvert !
vorbisenc ! oggmux ! filesink location=music.ogg
gst-launch-1.0 filesrc location=music.wav ! wavparse ! audioconvert !
lamemp3enc ! filesink location=music.mp3
Извлекает все треки из компакт-диска (CD) и преобразует их в один файл mp3:
gst-launch-1.0 cdparanoiasrc mode=continuous ! audioconvert !
lamemp3enc ! mpegaudioparse ! id3v2mux ! filesink location=cd.mp3
Извлекает трек 5 из CD и преобразует ео в один файл mp3:
gst-launch-1.0 cdparanoiasrc track=5 ! audioconvert !
lamemp3enc ! mpegaudioparse ! id3v2mux ! filesink location=track5.mp3
С использованием gst-inspect-1.0(1) становится возможным распознать настройки наподобие указанных выше для cdparanoiasrc, которые укажут ему сделать rip всего CD или только отдельных его треков. Альтернативно вы можете использовать URI и gst-launch-1.0, чтобы найти элемент (такой как cdparanoia), который поддерживает для вас этот протокол, например:
gst-launch-1.0 cdda://5 ! lamemp3enc vbr=new vbr-quality=6 !
filesink location=track5.mp3
Запишет звук из audio входа и закодирует его в файл ogg:
gst-launch-1.0 pulsesrc ! audioconvert ! vorbisenc ! oggmux !
filesink location=input.ogg
Video
Отобразит только видео составляющую из video-файла MPEG-1, с выводом в X display window:
gst-launch-1.0 filesrc location=JB_FF9_TheGravityOfLove.mpg !
dvddemux ! mpegvideoparse ! mpeg2dec ! xvimagesink
Отобразит только видео составляющую из файла .vob (используемого на DVD), выводя его в SDL window:
gst-launch-1.0 filesrc location=/flflfj.vob ! dvddemux !
mpegvideoparse ! mpeg2dec ! sdlvideosink
Проиграет и video и audio составляющие фильма MPEG:
gst-launch-1.0 filesrc location=movie.mpg ! dvddemux name=demuxer demuxer. !
queue ! mpegvideoparse ! mpeg2dec ! sdlvideosink demuxer. ! queue !
mpegaudioparse ! mpg123audiodec ! audioconvert ! audioresample ! pulsesink
Проиграет фильм AVI с потоком субтитров из внешнего текста:
gst-launch-1.0 filesrc location=movie.mpg ! mpegdemux name=demuxer demuxer. !
queue ! mpegvideoparse ! mpeg2dec ! videoconvert ! sdlvideosink demuxer. !
queue ! mpegaudioparse ! mpg123audiodec ! audioconvert ! audioresample ! pulsesink
Этот пример также показывает, как ссылаться на определенные пады по имени, если элемент (здесь: textoverlay) имеет несколько падов sink или падов source:
gst-launch-1.0 textoverlay name=overlay ! videoconvert ! videoscale !
autovideosink filesrc location=movie.avi ! decodebin ! videoconvert !
overlay.video_sink filesrc location=movie.srt ! subparse ! overlay.text_sink
Проиграет фильм AVI с потоком субтитров из внешнего текста, используя playbin:
gst-launch-1.0 playbin uri=file:///path/to/movie.avi suburi=file:///path/to/movie.srt
Сетевые потоки
Стриминг видео с помощью элементов RTP и сети. Эта команда запускается на передатчике:
gst-launch-1.0 v4l2src ! video/x-raw,width=128,height=96,format=UYVY ! videoconvert !
ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96 ! udpsink host=192.168.1.1 port=5000
Используйте эту команду на приемнике:
gst-launch-1.0 udpsrc port=5000 ! application/x-rtp, clock-rate=90000,payload=96 !
rtph263pdepay queue-delay=0 ! ffdec_h263 ! xvimagesink
Диагностика
Генерация null stream и игнорирование его (и печать подробностей).
gst-launch-1.0 -v fakesrc num-buffers=16 ! fakesink
Генерация чистого синуса для тестирования вывода audio:
gst-launch-1.0 audiotestsrc ! audioconvert ! audioresample ! pulsesink
Создаст привычный тестовый шаблон для тестирования видеовыхода:
gst-launch-1.0 videotestsrc ! xvimagesink
gst-launch-1.0 videotestsrc ! ximagesink
Автоматическая линковка
Вы можете использовать элемент decodebin для автоматического выбора правильных элементов для получения рабочего конвейера.
Проиграет любой поддерживаемый формат звука:
gst-launch-1.0 filesrc location=musicfile ! decodebin ! audioconvert !
audioresample ! pulsesink
Проиграет любой поддерживаемый формат видео с выводом video и audio. Потоки используются автоматически. Чтобы сделать это еще проще, вы можете использовать элемент playbin:
gst-launch-1.0 filesrc location=videofile ! decodebin name=decoder decoder. ! queue !
audioconvert ! audioresample ! pulsesink decoder. ! videoconvert ! xvimagesink
gst-launch-1.0 playbin uri=file:///home/joe/foo.avi
Фильтрованные соединения
Следующие примеры показывают, как использовать фильтрованные caps.
Покажет тестовую картинку и использует для этого видеоформат YUY2 или YV12.
gst-launch-1.0 videotestsrc ! 'video/x-raw,format=YUY2;video/x-raw,format=YV12' !
xvimagesink
Запишет звук и поместит его в .wav файл. Принудительное использование 16 .. 32-битных выборок со знаком и частоты дискретизации между 32 и 64 кГц:
gst-launch-1.0 pulsesrc ! 'audio/x-raw,rate=[32000,64000],format={S16LE,S24LE,S32LE}' !
wavenc ! filesink location=recording.wav
ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
GST_DEBUG Список с разделителем запятой категорий отладки (debug categories) и уровней отладки (debug levels), например GST_DEBUG=totem:4,typefind:5. Разрешено использовать '*' в качестве wildcard как часть имен категорий отладки (например GST_DEBUG=*sink:6,*audio*:6). Начиная с версии 1.2.0 можно указать уровень лога по имени (1=ERROR, 2=WARN, 3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE, 9=MEMDUMP), например GST_DEBUG=*audio*:LOG.
GST_DEBUG_NO_COLOR Когда эта переменная установлена, раскрашивание вывода отладки запрещено.
GST_DEBUG_DUMP_DOT_DIR Когда эта переменная установлена в путь файловой системы, сохраняет в него 'dot'-файлы графов конвейера (pipeline graphs). Это может быть впоследствии преобразовано в картинку с помощью утилиты 'dot' из набора инструментов graphviz, примерно так: dot foo.dot -Tsvg -o foo.svg (в качестве выходного формата также могут быть png или jpg). Есть также утилита 'xdot', которая может напрямую показать .dot без его предварительного преобразования.
Когда конвейер изменяет состояние через NULL на PLAYING и обратно на NULL, при каждом изменении состояния создается dot файл. Чтобы создать снимок состояния конвейера, отправьте процессу сигнал SIGHUP.
GST_REGISTRY Путь до файла реестра плагина. По умолчанию это ~/.cache/gstreamer-1.0/registry-CPU.bin, где CPU это тип machine/cpu, для которого был скомпилирован GStreamer, например 'i486', 'i686', 'x86-64', 'ppc', и т. п. (для подробностей проверьте "uname -i" и "uname -m").
GST_REGISTRY_UPDATE Установите в "no", чтобы заставить GStreamer подразумевать, что не были изменены, добавлены или удалены плагины. Это приведет к тому, что GStreamer пропускает начальную проверку, требуется ли заново перестроить кэш реестра. Это может быть полезно для встраиваемых окружений, где установленные плагины никогда не меняются. Не используйте эту опцию в любом другом случае.
GST_PLUGIN_PATH Укажет список директорий для сканирования дополнительных плагинов. Они имеют приоритет над системными плагинами.
GST_PLUGIN_SYSTEM_PATH Укажет список плагинов, которые всегда загружаются по умолчанию. Если не установлено, то по умолчанию используется системно инсталлированный путь, и плагины, установленные в домашнюю директорию пользователя.
GST_DEBUG_FILE Установите эту переменную в путь до файла, чтобы GStreamer перенаправлял в него все сообщения отладки. Если эта переменная не установлена, то сообщения отладки выводятся в стандартный поток вывода ошибок.
ORC_CODE Полезная переменная окружения Orc. Установите ORC_CODE=debug, чтобы разрешить отладчикам, таким как gdb, создавать backtraces из Orc-сгенерированного кода. Установите ORC_CODE=backup или ORC_CODE=emulate если подозреваете, что SIMD code generator Orc-а формирует некорректный код (довольно много важных плагинов GStreamer используют Orc, наподобие videotestsrc, audioconvert или audioresample).
G_DEBUG Полезная переменная окружения GLib. Установите G_DEBUG=fatal_warnings, чтобы программы GStreamer делали abort, когда произойдут критические предупреждения (critical warning), такие как assertion failure. Это пригодится, когда вы захотите разобраться, какая часть кода генерирует предупреждение, или в других похожих случаях. Просто установите G_DEBUG, как советовалось выше, и запустите программу в gdb (или позвольте ей сделать core dump). Затем отследите трассировку стека обычным способом.
ФАЙЛЫ
~/.cache/gstreamer-1.0/registry-*.bin
Это кэш плагинов; его можно в любое время удалить, он будет создан заново автоматически, когда не существует, или при изменении плагинов. В зависимости от XDG_CACHE_DIR его место размещения может быть другим.
СМ. ТАКЖЕ gst-inspect-1.0(1), gst-launch-1.0(1).
АВТОР Команда GStreamer http://gstreamer.freedesktop.org/
