[스터디 목표] GStreamer Basic Tutorial 전체를 리눅스 데스크탑 환경에서 구동해보기

[justinjoy]

목표

GStreamer 공식 Basic Tutorials 에 있는 모든 튜토리얼을 리눅스 데스크탑 환경에서 직접 빌드·실행해봅니다.

진행 방식

• 각자 로컬 리눅스 환경에서 Basic Tutorial 1번부터 끝까지 차례대로 따라가며 실행해봅니다.
• 실행 중 발견되는 이슈(빌드 실패, 의존성 문제, 동작 이상 등)를 메모해 둡니다.

다음 주 오프라인 모임에서 논의할 것

• 잘 동작하지 않거나 막히는 튜토리얼을 함께 모아서 이야기합니다.
• 환경/배포판별 차이, 해결 방법, 워크어라운드를 공유합니다.
• 필요한 경우 한글 번역 문서에 주의사항으로 반영하는 방안도 같이 검토합니다.

참고 링크

• 원문: https://gstreamer.freedesktop.org/documentation/tutorials/basic/index.html?gi-language=c
• 한글 번역 진행 현황: 이 저장소의 docs/ko/ 디렉터리

각자 진행하면서 발견한 점은 이 디스커션 댓글로 자유롭게 남겨주세요.

[jeonbyoung]

basic tutorial3 진행하면서 생긴 이슈입니다.
GStreamer 공식 Basic Tutorials 3에서 알려준 대로 gcc basic-tutorial-3.c -o basic-tutorial-3 'pkg-config --cflags --libs gstreamer-1.0'를 실행해보았는데, 아래와 같은 에러 로그가 발생합니다.

jeon@gst:~/gstreamer/subprojects/gst-docs/examples/tutorials$ gcc basic-tutorial-3.c -o basic-tutorial-3 `pkg-config --cflags --libs gstreamer-1.0`
basic-tutorial-3.c: In function ‘tutorial_main’:
basic-tutorial-3.c:108:17: error: implicit declaration of function ‘gst_state_get_name’; did you mean ‘gst_state_get_type’? [-Wimplicit-function-declaration]
  108 |                 gst_state_get_name (old_state), gst_state_get_name (new_state));
      |                 ^~~~~~~~~~~~~~~~~~
      |                 gst_state_get_type
basic-tutorial-3.c:107:52: warning: format ‘%s’ expects argument of type ‘char *’, but argument 2 has type ‘int’ [-Wformat=]
  107 |             g_print ("Pipeline state changed from %s to %s:\n",
      |                                                   ~^
      |                                                    |
      |                                                    char *
      |                                                   %d
  108 |                 gst_state_get_name (old_state), gst_state_get_name (new_state));
      |                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
      |                 |
      |                 int
basic-tutorial-3.c:107:58: warning: format ‘%s’ expects argument of type ‘char *’, but argument 3 has type ‘int’ [-Wformat=]
  107 |             g_print ("Pipeline state changed from %s to %s:\n",
      |                                                         ~^
      |                                                          |
      |                                                          char *
      |                                                         %d
  108 |                 gst_state_get_name (old_state), gst_state_get_name (new_state));
      |                                                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      |                                                 |
      |                                                 int

[justinjoy]

GStreamer를 정상적으로 찾지 못하는 것 같은데요.. 쉘에서 pkg-config --cflags --libs gstreamer-1.0 를 실행했을 때의 결과는 어떻게 나오나요? 혹은 설치된 GStreamer 버전이 어떻게 되나요?

[Yelihi]

저는 get_element_state_get_name 으로 변경하니 컴파일 되었습니다

예제 코드가 현재 버전과 맞지 않는 부분이 있는것 같습니다

[jeonbyoung]

@justinjoy
-I/usr/include/gstreamer-1.0 -I/usr/include/glib-2.0 -I/usr/lib/aarch64-linux-gnu/glib-2.0/include -I/usr/include/sysprof-6 -pthread -lgstreamer-1.0 -lgobject-2.0 -lglib-2.0 와 같이 나옵니다! gstreamer-1.0으로 설치했습니다.

[jeonbyoung]

@Yelihi 님이 알려주신대로 호출 함수명을 변경하니 잘 실행되더라구요. 현재 버전과 맞지 않아서 생긴 문제인 듯 합니다!

[cosuss]

#include <gst/gst.h>

int main(int argc, char *argv[]) {
GstElement *pipeline;
GstBus *bus;
GstMessage *msg;

gst_init(&argc, &argv);

pipeline = gst_parse_launch(
    "playbin uri=https://gstreamer.freedesktop.org/data/media/sintel_trailer-480p.webm",
    NULL
);

gst_element_set_state(pipeline, GST_STATE_PLAYING);

bus = gst_element_get_bus(pipeline);
msg = gst_bus_timed_pop_filtered(
    bus,
    GST_CLOCK_TIME_NONE,
    GST_MESSAGE_ERROR | GST_MESSAGE_EOS
);

if (msg != NULL) {
    gst_message_unref(msg);
}

gst_object_unref(bus);
gst_element_set_state(pipeline, GST_STATE_NULL);
gst_object_unref(pipeline);

return 0;

}

//이하 터미널 출력값

Starting build...
/usr/bin/gcc -fdiagnostics-color=always -g /home/park-jinhwan/gstreamer-study/basic-tutorial-1.c -o /home/park-jinhwan/gstreamer-study/basic-tutorial-1
/home/park-jinhwan/gstreamer-study/basic-tutorial-1.c:1:10: fatal error: gst/gst.h: No such file or directory
1 | #include <gst/gst.h>
| ^~~~~~~~~~~
compilation terminated.

Build finished with error(s).

이런식의 오류가 생기는데, 기본 ubuntu terminal에서만 컴파일 해야하는 건지 궁금합니다. chatgpt도 vscode terminal 보다는 기본 terminal을 추천하더라고요. 특별한 이유가 있을까요..?

[justinjoy]

vscode terminal 보다는 기본 terminal을 추천

그런건 아니구요.. pkg-config --cflags --libs gstreamer-1.0 이 부분이 컴파일할때 빠져서 헤더를 못찾아서 발생한 에러입니다. :)

[cosuss]

아하 감사합니다..!

[dayforday2468]

#!/usr/bin/env python3
import logging
import sys

import gi

gi.require_version("GLib", "2.0")

from gi.repository import Gst

logging.basicConfig(level=logging.DEBUG, format="[%(name)s] [%(levelname)8s] - %(message)s")
logger = logging.getLogger(__name__)


def pad_added_handler(src, new_pad):
    sink_pad = convert.get_static_pad("sink")
    logger.info(f"Received new pad '{new_pad.name}' from '{src.name}'.")

    # If our converter is already linked, we have nothing to do here
    if sink_pad.is_linked():
        logger.info("We are already linked. Ignoring.")
        sys.exit()

    # Check the new pad's type
    new_pad_caps = new_pad.get_current_caps()
    new_pad_struct = new_pad_caps.get_structure(0)
    new_pad_type = new_pad_struct.get_name()
    if not new_pad_type.startswith("audio/x-raw"):
        logger.info(f"It has type '{new_pad_type}' which is not raw audio. Ignoring.")
        return

    # Attempt the link
    ret = new_pad.link(sink_pad)
    if ret != Gst.PadLinkReturn.OK:
        logger.error(f"Type is '{new_pad_type}' but link failed.")
    else:
        logger.info(f"Link succeeded (type '{new_pad_type}').")


# Initialize GStreamer
Gst.init(sys.argv[1:])

# Create the elements
source = Gst.ElementFactory.make("uridecodebin", "source")
convert = Gst.ElementFactory.make("audioconvert", "convert")
resample = Gst.ElementFactory.make("audioresample", "resample")
sink = Gst.ElementFactory.make("autoaudiosink", "sink")

# Create the empty pipeline
pipeline = Gst.Pipeline.new("test-pipeline")

if not pipeline or not source or not convert or not resample or not sink:
    logger.error("Not all elements could be created.")
    sys.exit(1)

# Build the pipeline. Note that we are NOT linking the source at this
# point. We will do it later.
pipeline.add(source, convert, resample, sink)
if not convert.link(resample) or not resample.link(sink):
    logger.error("Elements could not be linked.")
    sys.exit(1)

# Set the URI to play
source.set_property("uri", "https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm")

# Connect to the pad-added signal
source.connect("pad-added", pad_added_handler)

# Start playing
ret = pipeline.set_state(Gst.State.PLAYING)
if ret == Gst.StateChangeReturn.FAILURE:
    logger.error("Unable to set the pipeline to the playing state.")
    sys.exit(1)

# Listen to the bus
bus = pipeline.get_bus()
terminate = False
while not terminate:
    msg = bus.timed_pop_filtered(1 * Gst.SECOND, Gst.MessageType.STATE_CHANGED | Gst.MessageType.ERROR | Gst.MessageType.EOS)

    # Parse message
    if msg:
        if msg.type == Gst.MessageType.ERROR:
            err, debug_info = msg.parse_error()
            logger.error(f"Error received from element {msg.src.get_name()}: {err.message}")
            logger.error(f"Debugging information: {debug_info if debug_info else 'none'}")
            terminate = True
        elif msg.type == Gst.MessageType.EOS:
            logger.info("End-Of-Stream reached.")
            terminate = True
        elif msg.type == Gst.MessageType.STATE_CHANGED:
          # We are only interested in state-changed messages from the pipeline
          if msg.src == pipeline:
            old_state, new_state, pending_state = msg.parse_state_changed()
            logger.info("Pipeline state changed from", old_state, "to", new_state)
        else:
            # We should not reach here
            logger.error("Unexpected message received.")

pipeline.set_state(Gst.State.NULL)

(gstpy)
kmc@cation MINGW64 ~/OSSCA_2026/gstreamer/subprojects/gst-docs/examples/tutorials/python (main)
$ python basic-tutorial-3.py
C:\Users\hon05\OSSCA_2026\gstreamer\subprojects\gst-docs\examples\tutorials\python\basic-tutorial-3.py:9: PyGIWarning: Gst was imported without specifying a version first. Use gi.require_version('Gst', '1.0') before import to ensure that the right version gets loaded.
from gi.repository import Gst
Traceback (most recent call last):
File "C:\Users\hon05\OSSCA_2026\gstreamer\subprojects\gst-docs\examples\tutorials\python\basic-tutorial-3.py", line 58, in
pipeline.add(source, convert, resample, sink)
TypeError: Gst.Bin.add() takes exactly 2 arguments (5 given)

혹시 파이썬 쓰시는 분 중에 add 여러 개 동시에 하면 저처럼 에러나는 분 있으세요? 원본 튜토리얼 코드엔 add 여러 개 동시에 하도록 짜져 있는데, 제가 돌리면 자꾸 안되네요.

[dayforday2468]

그리고 의도된 건지 모르겠는데, python 튜토리얼 4번엔 유독 오타가 많습니다. 오타, 버그 잡으면서 연습하라는 의미라면 이해하겠는데, 소스 코드가 애초에 튜토리얼에 적힌 것처럼 돌아가지 않는데, 이걸 안 돌려보고 넣어둔 건지 의심이 됩니다.

[justinjoy]

오.. python 버전때문에 발생하는 에러일수도 있어요. 생각보다 메인테이너들이 python을 신경쓰지는 않거든요. 에러에 대해서 리포팅해서 수정 커밋을 보내면 좋아할겁니다. :)

[dayforday2468]

#!/usr/bin/env python3
import logging
import sys

import gi

gi.require_version('Gst', '1.0')
gi.require_version('GLib', '2.0')

from gi.repository import Gst, GLib


logging.basicConfig(level=logging.DEBUG, format="[%(name)s] [%(levelname)8s] - %(message)s")
logger = logging.getLogger(__name__)


class CustomData:
    def __init__(self):
        self.playbin = None
        self.main_loop = None
        self.n_video = 0
        self.n_audio = 0
        self.n_text = 0

        # playbin flags
        self.GST_PLAY_FLAG_VIDEO = 1
        self.GST_PLAY_FLAG_AUDIO = 2
        self.GST_PLAY_FLAG_TEXT = 4



data = CustomData()


# Process messages from GStreamer
def handle_message(bus, msg):

    if msg.type == Gst.MessageType.ERROR:
        err, debug_info = msg.parse_error()
        logger.error(f"Error received from element {msg.src.get_name()}: {err.message}")
        logger.error(f"Debugging information: {debug_info if debug_info else 'none'}")
        data.main_loop.quit()

    elif msg.type == Gst.MessageType.EOS:
        logger.info("End-Of-Stream reached.")
        data.main_loop.quit()

    elif msg.type == Gst.MessageType.STATE_CHANGED:
        old_state, new_state, pending_state = msg.parse_state_changed()
        if msg.src == data.playbin:
            if new_state == Gst.State.PLAYING:
                # Once we are in the playing state, analyze the streams
                analyze_streams()

    return True


# Extract some metadata from the streams and print it on the screen
def analyze_streams():
    data.n_video = data.playbin.get_property("n-video")
    data.n_audio = data.playbin.get_property("n-audio")
    data.n_text = data.playbin.get_property("n-text")

    print(f"{data.n_video} video stream(s), {data.n_audio} audio stream(s), {data.n_text} text stream(s)\n")

    for i in range(data.n_video):
        tags = data.playbin.emit("get-video-tags", i)
        if tags:
            print(f"video stream {i}:")
            ok, codec = tags.get_string(Gst.TAG_VIDEO_CODEC)
            print(f"  codec: {codec if ok else 'unknown'}")

    print()
    for i in range(data.n_audio):
        tags = data.playbin.emit("get-audio-tags", i)
        if tags:
            print(f"audio stream {i}:")
            ok, codec = tags.get_string(Gst.TAG_AUDIO_CODEC)
            if ok:
                print(f"  codec: {codec}")

            ok, language = tags.get_string(Gst.TAG_LANGUAGE_CODE)
            if ok:
                print(f"  language: {language}")

            ok, bitrate = tags.get_uint(Gst.TAG_BITRATE)
            if ok:
                print(f"  bitrate: {bitrate}")

    print()
    for i in range(data.n_text):
        tags = data.playbin.emit("get-text-tags", i)
        if tags:
            print(f"subtitle stream {i}:")
            ok, language = tags.get_string(Gst.TAG_LANGUAGE_CODE)
            if ok:
                print(f"  language: {language}")

    current_video = data.playbin.get_property("current-video")
    current_audio = data.playbin.get_property("current-audio")
    current_text = data.playbin.get_property("current-text")

    print()
    print(
        f"Currently playing video stream {current_video}, "
        f"audio stream {current_audio} and text stream {current_text}"
    )
    print("Type any number and hit ENTER to select a different audio stream")


# Process keyboard input
def handle_keyboard(source, condition):
    result = source.read_line()
    if not result:
        return True

    status, line, _, _ = result

    if status == GLib.IOStatus.NORMAL and line is not None:
        line = line.strip()

        if not line.isdigit():
            logger.error("Index out of bounds")
            return True

        index = int(line)
        if index < 0 or index >= data.n_audio:
            logger.error("Index out of bounds")
        else:
            # If the input was a valid audio stream index, set the current audio stream
            logger.info(f"Setting current audio stream to {index}")
            data.playbin.set_property("current-audio", index)

    return True


# initialize GStreamer
Gst.init(sys.argv[1:])

# Create the elements
data.playbin = Gst.ElementFactory.make("playbin", "playbin")

if not data.playbin:
    logger.error("Not all elements could be created.")
    sys.exit(1)

# Set the URI to play
data.playbin.set_property("uri", "https://gstreamer.freedesktop.org/data/media/sintel_cropped_multilingual.webm")

# Set flags to show Audio and Video but ignore Subtitles
flags = data.playbin.get_property("flags")
flags |= (data.GST_PLAY_FLAG_VIDEO | data.GST_PLAY_FLAG_AUDIO)
flags &= ~data.GST_PLAY_FLAG_TEXT
data.playbin.set_property("flags", flags)


# Set connection speed. This will affect some internal decisions of playbin
data.playbin.set_property("connection-speed", 56)

# Add a bus watch, so we get notified when a message arrives
bus = data.playbin.get_bus()
bus.add_signal_watch()
bus.connect("message", handle_message)

# Add a keyboard watch so we get notified of keystrokes
io_stdin = GLib.IOChannel(sys.stdin.fileno())
GLib.io_add_watch(io_stdin, GLib.IOCondition.IN, handle_keyboard)


# Start playing
ret = data.playbin.set_state(Gst.State.PLAYING)
if ret == Gst.StateChangeReturn.FAILURE:
    print("Unable to set the pipeline to the playing state.")
    sys.exit(1)

# Create a GLib Main Loop and set it to run
data.main_loop = GLib.MainLoop()
data.main_loop.run()

data.playbin.set_state(Gst.State.NULL)

파이썬에 예제 추가하는 중입니다. 위 예제는 playback-tutorial-1..py입니다. 혹시 python으로 하시는 분 있다면 돌려보고 오류가 있는지 알려주세요! 목표는 하루에 하나씩 추가해보는 것이네요!

[justinjoy]

https://gitlab.freedesktop.org/gstreamer/gstreamer/-/tree/main/subprojects/gst-python?ref_type=heads gst-python 프로젝트의 examples 코드도 참고해주세요~

[dayforday2468]

basic-tutorial-5.py, playback-tutorial-2.py를 완성했는데, 환경문제로 잘 안돌아가네요.
conda create -n gstpy -c conda-forge python=3.12 pygobject gstreamer -y
conda install -c conda-forge gtk3 -y
이렇게 gstpy 가상환경을 만들었습니다.

(gstpy)
kmc@cation MSYS ~/OSSCA_2026/gstreamer/subprojects/gst-docs/examples/tutorials/python (add-python-tutorial)
$ conda list | grep -Ei "gstreamer|gst-|pygobject|gtk|glib"
glib 2.86.4 h19e2e61_1 conda-forge
glib-networking 2.80.0 hb149071_0 conda-forge
glib-tools 2.86.4 he647baa_1 conda-forge
gst-libav 1.28.2 h33fb14b_1 conda-forge
gst-plugins-bad 1.28.2 pl5321h55d442d_1 conda-forge
gst-plugins-base 1.28.2 hbf50fad_2 conda-forge
gst-plugins-good 1.28.2 ha7de1bd_2 conda-forge
gst-plugins-ugly 1.28.2 he851bb2_1 conda-forge
gstreamer 1.28.2 hae9036a_2 conda-forge
gtk3 3.24.52 h20ae452_0 conda-forge
libglib 2.86.4 h0c9aed9_1 conda-forge
pygobject 3.56.2 py312hc4f808e_0 conda-forge

필요한 패키지가 다 있는 것도 확인했습니다.

(gstpy)
kmc@cation MSYS ~/OSSCA_2026/gstreamer/subprojects/gst-docs/examples/tutorials/python (add-python-tutorial)
$ gst-inspect-1.0 theoradec
gst-inspect-1.0 katedec
gst-inspect-1.0 --plugin theora
gst-inspect-1.0 --plugin kate
No such element or plugin 'theoradec'
No such element or plugin 'katedec'
No such element or plugin 'theora'
No such element or plugin 'kate'

그런데, playback-tutorial-2.py를 돌리기 위해 필요한 디코더가 위와 같이 없습니다.
그 결과, 비디오와 자막 스트림을 인식하지 못하고 있습니다.

(gstpy)
kmc@cation MSYS ~/OSSCA_2026/gstreamer/subprojects/gst-docs/examples/tutorials/python (add-python-tutorial)
$ gst-inspect-1.0 gtkglsink
gst-inspect-1.0 gtksink
No such element or plugin 'gtkglsink'
No such element or plugin 'gtksink'

또한, basic-tutorial-5.py를 돌리기 위해 필요한 gtk 관련 element도 위와 같이 없습니다. (gtk3는 가상환경 만들면서 설치했습니다.)

GPT한테 물어보니, Window용 GStreamer 배포판 설치를 권장하던데, 다른 분들은 어떻게 하시고 계신지 궁금하네요.

[dayforday2468]

공식 사이트에서 [MSVC x86_64 (VS 2022, Release CRT)] 설치해도 비슷하네요. 차이점은 theora 관련 디코더가 있어서 playback-tutorial-2.py에서 비디오가 보인다는 점인데.... gtk 관련해서는 여기서도 element가 전부 없는 상황이네요 ㅠㅠ 자막도 kate 관련 디코더가 없어서 여전히 인식하지 못하구요.