오픈소스 프로젝트 활용 실습 멘토링 기간(5/4~6/2) 동안 프로젝트 계획서 초안 작성해보았읍니다,,^^

[gmgmgun]

프로젝트 계획서 — GStreamer 기반 Video Stabilization

1. 프로젝트 개요

본 계획서는 OSSCA 체험형 GStreamer 파트의 4주 실습 멘토링 기간에 대한 개인 활동 계획이다. 체험형 프로그램의 취지에 따라 오픈소스 기여 실적이 아닌, 오픈소스 프로젝트에 참여·기여하기 위한 협업 도구와 워크플로의 체험, 그리고 분야 오픈소스(GStreamer)에 대한 학습을 무게중심으로 둔다.

팀은 영상 안정화(Video Stabilization)를 공통 실습 주제로 선정했고, 개인 트랙 형식으로 진행한다. 데이터셋을 활용한 영상 후보정(Offline Stabilization)을 GStreamer 파이프라인에서 구현하는 것이 공통 실습 결과물이며, 안정화 알고리즘 자체는 검증된 오픈소스 구현(OpenCV)을 도구로 활용하고, 학습의 무게는 GStreamer 파이프라인 위에서의 영상 처리 통합 경험에 둔다.

본 계획서의 위치: 본 계획서는 멘티가 프로그램 시작 전 미리 그려본 학습 계획이며, 실제 진행은 멘토의 안내와 팀 운영 방식에 따라 조정한다. 특히 §9 주차별 학습 순서, §8 PR 단위, §7 단계별 도달 시점은 W1 멘토링 시작 후 멘토와의 합의를 거쳐 확정한다.

2. 목표

• GStreamer 학습: 파이프라인 통합 경험 — caps 협상, appsink/appsrc 기반 외부 처리 연동, 타임스탬프·EOS 관리, 디버깅 워크플로
• 공통 실습: 공개 데이터셋 기반 Video Stabilization 후보정을 GStreamer 파이프라인에서 구현
• 오픈소스 협업 워크플로 체험: 팀 공용 레포지토리에서 fork-branch-PR-review-merge 사이클을 직접 돌려봄으로써 오픈소스 협업의 표준 워크플로를 체험

3. 제약 사항

• 기간: 2026년 5월 4일 ~ 6월 2일 (약 4주)
• 진행 방식: 개인 트랙
• 수준: GStreamer 초심자
• 공통 실습 주제: Video Stabilization 후보정

4. W0 — 프로젝트 시작 전 사전 준비 (~5/2)

W1 시작 전 W0 기간(~5/2)에 다음 항목들을 미리 처리해두어 W1을 정상 출발한다. 환경 세팅에서 막히면 4주 일정 전체가 흔들리므로 이 사전 준비가 일정 성공의 핵심 변수이다.

환경 세팅

• GStreamer 설치 및 동작 검증 (필수)

  • OS에 맞는 방법으로 GStreamer 1.0 설치 (Windows: 공식 인스톨러 Complete 옵션, macOS: brew install gstreamer, Ubuntu: apt install gstreamer1.0-tools 외 plugins-base/good/bad/ugly/libav 패키지)
  • gst-launch-1.0 --version 동작 확인
  • gst-inspect-1.0 avidemux, gst-inspect-1.0 jpegdec 동작 확인 (DeepStab 처리에 필요한 element 가용성 검증)

• Python 환경 + GStreamer 바인딩 (Python으로 갈 경우)

  • Python 3.x, OpenCV (pip install opencv-python), GStreamer Python 바인딩(python3-gi, python3-gst-1.0 또는 OS별 동등 패키지)
  • 간단한 Gst.parse_launch() 한 줄 코드로 import 검증

• (선택) ffmpeg 설치

  • 디버깅 클립 자르기 등에 유용. 필수는 아님

데이터셋 사전 확인

• DeepStab 데이터셋(약 8GB) 다운로드(브라우저 url에 http://cg.cs.tsinghua.edu.cn/download/DeepStab.zip 붙여넣어 진행) 및 압축 해제 완료
• 폴더 구조: unstable/, stable/로 분리, 동일 파일명으로 페어 매칭
• 영상 사양: AVI/MJPEG, 1280×720, 29.97fps, 클립당 약 15초

동작 검증 — 한 줄 명령어

다음 명령어가 정상 재생되면 환경 세팅 + 데이터셋 + 디코딩 파이프라인의 핵심 element 동작 검증이 한 번에 끝난다.

gst-launch-1.0 filesrc location="<DeepStab 경로>/stable/1.avi" ! avidemux ! jpegdec ! videoconvert ! autovideosink

또는 decodebin 자동 인식 버전:

gst-launch-1.0 filesrc location="<DeepStab 경로>/stable/1.avi" ! decodebin ! videoconvert ! autovideosink

참고 자료 사전 탐색 (W1 시간 절약)

• appsink/appsrc + OpenCV 연동 reference 예제: GitHub에서 "gstreamer appsink opencv python" 검색하여 동작하는 예제 1~2개 미리 확보. 본 프로젝트 최대 절벽인 appsink/appsrc 왕복 학습 시간을 절반 이상 줄여줌.
• GStreamer Application Development Manual의 appsink/appsrc 챕터 한 번 통독
• OpenCV Video Stabilization 튜토리얼 한 번 훑어보기

5. 학습 대상 GStreamer 표면

본 프로젝트가 다루는 GStreamer 학습 영역을 명시한다. 알고리즘 학습이 아닌 통합·운영 학습이 핵심이다.

• 요소(element) 학습: filesrc, avidemux, jpegdec, videoconvert, videoscale, capsfilter, queue, tee, x264enc, rtph264pay, udpsink, hlssink2, appsink, appsrc, autovideosink, fpsdisplaysink
• 개념 학습: Pads와 Caps 협상, Bus와 메시지(EOS·ERROR·상태 전이), Buffer와 PTS/DTS/duration, Queue를 통한 스레드 분리와 latency 흡수, Clock·base time·is-live 속성, Bin 구조
• 외부 처리 통합: appsink push/pull 모드, gst_buffer_map을 통한 메모리 매핑, appsrc의 타임스탬프 직접 관리, look-ahead 처리로 인한 지연 흡수
• 디버깅 워크플로: gst-inspect-1.0로 요소 명세 확인, gst-launch-1.0로 파이프라인 빠른 검증, gst-discoverer-1.0로 미디어 사양 확인, GST_DEBUG 레벨별 로깅(특히 sync, latency, pts 카테고리), GST_DEBUG_DUMP_DOT_DIR을 활용한 파이프라인 그래프 덤프

6. 개인 트랙 — 세 스트림 송출 + Sync 학습

트랙 정체성

공개 데이터셋 DeepStab의 영상을 활용하여 불안정 / 안정 / 후보정 세 스트림을 GStreamer로 송출하는 것을 목표로 한다.

• 불안정: DeepStab의 unstable/ 영상
• 안정: DeepStab의 stable/ 영상 (페어 매칭)
• 후보정: 본인이 OpenCV로 안정화한 결과

데이터셋 사전 확인

DeepStab 다운로드(브라우저 url에 http://cg.cs.tsinghua.edu.cn/download/DeepStab.zip 붙여넣어 진행) 및 압축 해제 완료. unstable/, stable/ 폴더로 분리되어 있으며 동일 파일명으로 페어 매칭됨. 영상 사양은 다음과 같다.

• 컨테이너: AVI
• 코덱: MJPEG (Motion JPEG)
• 해상도: 1280×720
• Framerate: 29.97fps (정확히 30000/1001)
• 클립 길이: 약 15초, 465프레임
• Pixel format: yuvj420p

MJPEG는 모든 프레임이 I-frame이라 B-frame 부재로 PTS 처리가 단순하고 랜덤 액세스가 빠르다는 장점이 있어 본 프로젝트의 학습 환경으로 적합하다. 송출 단계에서 호환성이 필요한 경우 H.264 재인코딩(x264enc)을 적용한다.

클립 선택

DeepStab은 클립별 카테고리 구분 없이 번호로만 분류되어 있다. 본 트랙은 영상 미리보기로 클립을 살펴본 뒤 저주파·소진폭 평행이동 위주의 흔들림 패턴(예: 보행 시점 촬영)을 가진 클립을 1~2개 선정하여 메인 데모용으로 사용한다. 이는 본 트랙이 채택한 2D affine + moving average 안정화 알고리즘에 가장 적합한 흔들림 특성이다. 클립 선정은 W1 작업 중 진행한다.

데이터셋 특성 이해

DeepStab의 stable 영상은 하드웨어 스타빌라이저(예: DJI Osmo)로 안정화된 카메라로 촬영된 것으로, 카메라의 떨림과 회전은 제거되었으나 보행자의 이동으로 인한 카메라 위치 변화는 남아있다. 2D affine 안정화 알고리즘 또한 같은 영역(회전·진동)을 다루므로, 후보정 결과와 데이터셋의 stable 영상이 유사한 잔여 특성을 보일 것으로 예상된다. 이는 알고리즘의 한계가 아니라 2D 안정화의 본질적 특성이며, 활동보고서에서 학습 포인트로 다룬다.

환경과 방식 — 자유

처리·송출 환경과 방식은 고정하지 않는다. 4주 일정에 맞춰 가장 단순한 방식(파일 저장 후 동시 재생, 로컬 디스플레이)을 1차 목표로 두며, 송출 방식 확장은 stretch로 둔다.

핵심 학습 포인트 — Sync 처리

후보정 안정화는 look-ahead 평활화로 인해 N프레임의 본질적 latency를 가진다. 세 스트림 동시 재생 시 후보정만 N프레임 뒤처져 보이는 sync 문제가 필연적으로 발생한다. 본 트랙은 이 sync 문제를 다루는 과정에서 GStreamer의 시간·버퍼·동기화 모델(PTS 정책, queue 운용, is-live 속성, latency 협상)을 실습 형태로 체험하는 것을 핵심 학습 포인트로 둔다.

완벽한 sync 일치를 결과물로 요구하지 않으며, 시도·관찰·기록 자체를 학습 산출물로 본다. 1차 목표 단계에서 최소 1회의 sync 처리 시도와 그 결과 관찰 기록을 포함한다.

7. 단계적 성공 기준

개인 트랙은 단일 성공 기준이 아닌 단계적 도달점으로 정의한다. 4주 일정에 맞추어 1차 목표를 설정하고, 2차 목표를 stretch로 통합한다.

파이프라인 구성 (DeepStab 사양 반영)

• 입력: filesrc → avidemux → jpegdec
• 변환: videoconvert → capsfilter(video/x-raw,format=BGR,framerate=30000/1001)로 OpenCV 호환 포맷과 정확한 framerate 보존
• 처리: appsink 콜백에서 프레임 추출 → OpenCV 안정화 → appsrc로 재주입 (PTS 간격 1001/30000초 기준)
• 출력: 1차 목표는 파일 저장 또는 로컬 디스플레이

1차 목표 (W4 종료 시점, minimum)

• 720p, 29.97fps의 DeepStab 클립에 대해 세 영상(불안정/안정/후보정)이 각각 끊김 없이 재생되는 결과물 생성
• 세 영상을 같은 화면에 동시에 띄울 수 있음
• appsink/appsrc 왕복에서 caps·PTS·EOS 처리 정상화
• 최소 1회의 sync 처리 시도와 결과 관찰 기록 (성공 여부 무관)

Stretch (W4 여유 시, 못 해도 OK)

• 송출 방식 확장 (RTP, HLS 등) — 같은 LAN의 다른 머신·브라우저에서 수신 확인
• Sync 좁히기 본격 시도 (세 스트림 시각 정렬 품질 향상)
• 더 복잡한 송출 방식 시도 (WebRTC 등)
• RPi 등 임베디드 환경으로 포팅 (MJPEG는 디코딩 부담이 작아 임베디드에도 유리)
• compositor로 세 영상 합성 후 단일 스트림 송출
• 더 도전적인 흔들림 패턴(고주파 진동·빠른 회전·차량 시점 등)을 가진 클립으로 알고리즘 한계 검증

알고리즘 범위 (의도적 단순화)

• 2D point feature 기반 안정화(특징점 추적 → affine 변환 추정 → moving average 평활화 → 보정)에 한정
• 보정 후 검은 테두리는 고정 비율 크롭으로 단순 처리
• Rolling shutter, mesh-based, 3D, 딥러닝 기반은 범위 외

실패 시 대응

• 1차 목표 미달 시: 짧은 클립(5초 내외)으로 한정, 2-스트림(불안정/후보정)으로 폴백 검토

8. 오픈소스 협업 워크플로 체험

체험형 취지의 핵심 한 축인 협업 도구·워크플로 체험을 다룬다. 외부 오픈소스에 대한 PR은 4주 안에 피드백 사이클이 돌기 어렵다는 현실을 고려해, 팀 공용 레포지토리를 만들어 오픈소스 협업 사이클을 팀 내부에서 그대로 재현하는 방식으로 진행한다.

레포지토리 구조 (제안)

ossca-gst-stabilization/
├── README.md
├── common/              # 공통 코드 (공통 파이프라인 유틸 등)
├── docs/                # 학습 노트, 트러블슈팅 모음
├── tracks/
│   ├── [팀원 A]/ # 세 스트림 송출
│   ├── [팀원 B]/
│   └── [팀원 C]/
└── .github/
    └── PULL_REQUEST_TEMPLATE.md

각 팀원이 upstream 레포를 fork하고, feature branch에서 작업 후 PR을 올리는 방식으로 진행한다. 개인 트랙 형식은 유지되며, 공용 레포는 작업 내용 통합이 아닌 Git 협업 사이클을 돌리는 공동 운동장으로 기능한다.

체험할 워크플로

• Fork & upstream 동기화
• Feature branch 전략, commit 컨벤션
• PR 작성, 코드 리뷰, merge conflict 해결
• Issue tracker로 본인 작업 단위 관리

개인 트랙 PR 단위 (예시)

작업을 작은 PR 단위로 쪼개어 협업 사이클을 자주 돌리는 것을 원칙으로 한다. 예시 분할은 다음과 같으며, 실제 단위와 순서는 작업 진행에 따라 변경될 수 있다.

• 데이터셋 처리 + 기본 디코딩 파이프라인 (filesrc → avidemux → jpegdec → videoconvert → autovideosink)
• appsink 프레임 추출
• OpenCV 안정화 모듈
• appsrc 재주입 + caps/PTS/EOS 정상화
• 세 스트림 동시 재생 + sync 시도
• (Stretch) 송출 방식 확장 또는 sync 본격 처리

외부 오픈소스 기여 (Stretch)

위 내부 사이클을 돌리는 과정에서 마주친 GStreamer 공식 문서·예제의 미흡한 점을 docs/에 누적하고, 여건이 되면 W3~W4에 외부 PR/MR을 시도한다. 머지 여부는 평가 대상이 아니며, 시도 자체를 활동보고서에 기록한다.

9. 일정

본 일정은 멘티가 미리 그려본 안이며, W1 멘토링 시작 후 멘토 안내에 따라 조정될 수 있다.

주차	날짜	팀 공통	본인
W0	~5/2	팀 공용 레포 도입 사전 합의, 멘토 사전 인사	GStreamer 환경 세팅 및 동작 검증, DeepStab 디코딩 한 줄 명령어 검증, appsink/appsrc reference 예제 사전 확보, OpenCV 안정화 튜토리얼 통독 (상세는 §4)
W1	5/4 ~ 5/10	GStreamer 환경 검증, 팀 공용 레포 셋업 및 첫 PR(README·구조), Pads/Caps · Bus/EOS · Queue · appsink/appsrc 패턴 학습	DeepStab 디코딩 파이프라인 + 클립 선정, autovideosink 재생 검증, appsink 프레임 추출 시작
W2	5/11 ~ 5/17	appsink/appsrc/OpenCV 통합 학습, GST_DEBUG/.dot 디버깅 워크플로	OpenCV 안정화 모듈, appsrc 재주입 + caps/PTS/EOS 정상화 (W2 후반 도달 목표)
W3	5/18 ~ 5/24	후보정 프로토타입 마무리, 코드 리뷰 라운드	세 스트림 동시 재생 + sync 시도 1회 (1차 목표)
W4	5/25 ~ 6/2	발표 준비, 활동보고서 작성, 외부 PR 시도(여건 시)	데모 영상 녹화, 여유 시 송출 방식 확장 또는 sync 본격 시도 (Stretch), 활동보고서 작성

10. 산출물

체험형 프로그램의 공식 산출물인 멘티 개별 활동보고서를 W4에 제출한다. 분량은 멘토 안내에 따른다 (W1 중 확인). 보고서에는 다음을 포함한다.

• GStreamer 학습 결과: 학습한 요소·개념 정리, 막혔던 지점과 해결 과정
• 데이터셋 사전 확인 결과: DeepStab 사양 정리, 페어 매칭 검증, 클립 선정 기준
• 본인 트랙 결과물: 파이프라인 구성도(.dot 덤프), 세 스트림 재생 데모 영상(불안정/안정/후보정 비교)
• Sync 학습 기록: latency 발생 원인 분석, 시도한 처리 방식, 결과 관찰 (성공/실패 무관)
• 협업 워크플로 체험 기록: 팀 공용 레포 링크, 본인이 올린 PR 목록과 리뷰 기록, 마주친 conflict와 해결 과정
• 외부 기여 시도 기록 (있을 경우): 시도한 PR/MR 링크 또는 정리한 노트

11. 참고 자료

• GStreamer 공식 문서 — https://gstreamer.freedesktop.org
• GStreamer Application Development Manual (appsink/appsrc 챕터)
• GStreamer GitLab 저장소 — https://gitlab.freedesktop.org/gstreamer
• OpenCV Video Stabilization 튜토리얼
• DeepStab 데이터셋 — Wang et al., "Deep Online Video Stabilization with Multi-Grid Warping Transformation Learning", IEEE TIP 2019

[gmgmgun]

저번주 미팅 때 나온 주제(video stabilization)를 기반으로

1. GStreamer를 메인으로 학습하는가(3 스트림 동시송출 및 sync) ,
2. Git을 활용하는가(git fork 와 branch를 활용한 pr 경험),
3. 적절한 학습 난이도인가(stretch 및 fallback 도입),
4. 학습 내용을 토대로 프로젝트를 발전시킬 수 있는가(현재 video stabilization에 관련된 플러그인은 유료만 있음)
   을 주안점으로 작성하였습니다.