와우자 스트리밍 엔진 확장 모듈(이하 와우자 모듈)은 와우자 스트리밍 엔진(Wowza Streaming Engine, 이하 와우자)이 다양한 추가 기능을 구현할 수 있게 해 준다. 와우자에서 직접 배포하는 모듈뿐 아니라, 필요에 따라 사용자가 직접 자바(Java)를 이용해 개발해서 사용할 수도 있다.
와우자는 자바를 기반으로 동작한다. 때문에 자바를 이용해 제작된 와우자 모듈은 단순한 REST API를 통한 연동 및 제어를 넘어, 훨씬 세밀하고 폭넓게 사용자의 요구에 대응할 수 있다. 예를 들어, 시스템 장애 발생 시 자동으로 Failover를 수행하거나, 큐톤(SCTE-35)을 추가해 자동으로 광고를 삽입하고, Azure’s AI Speech Services와 연동해 실시간 화면 해설 폐쇄자막(Closed Caption)을 구현하는 등의 기능이 가능해진다.
와우자에서 기본 제공하는 다양한 기능의 확장 모듈이 존재한다. 많은 사용자가 필요로 하는 기능들을 중심으로 개발되었으며, 기본 확장 모듈만으로도 많은 작업들이 가능해진다.
와우자 엔진용 확장 모듈 목록
다음은 깃허브를 통해 배포되는 와우자 엔진용 확장 모듈들이다. 이 목록 이외에도 많은 확장 모듈들이 존재한다. 각 확장 모듈 이름을 클릭하면 공식 배포 페이지로 연결되며, 설명에 링크가 있는 경우, 용도와 설정하는 방법을 다룬 게시글로 연결된다.
Origin/Edge 구성에서 엣지 서버가 요청받은 스트림을 제공할 오리진 서버를 동적으로 결정한다. 여러 오리진의 상태나 스트림 위치에 따라 요청 경로를 해석하는 분산 스트리밍 CDN 구성에 사용할 수 있다.
와우자 스트리밍 엔진 확장 모듈 설치 방법
Step 1 : 와우자 모듈 준비
와우자는 자바(Java) 환경에서 실행된다. 때문에, 와우자 모듈 역시 자바로 만들어지며, JAR(Java Archive) 파일 형태로 사용된다. 대부분의 경우 이미 컴파일된 JAR 파일이 제공되지만, 컴파일에 사용된 라이브러리 버전에 문제가 있거나 소스만 제공되는 경우, 소스를 다운받아 직접 컴파일하면 된다.
확장 모듈 파일이 준비되었다면, 본격적인 적용을 시작할 수 있다.
Step 2 : 와우자 모듈 파일 복사
준비한 와우자 모듈 파일(JAR 파일)을 와우자 설치 경로에 있는 라이브러리 디렉토리에 복사한다. 라이브러리 디렉토리의 기본 경로는 아래와 같다.
리눅스 : /usr/local/WowzaStreamingEngine-(버전)/lib
윈도우 : C:\Program Files\Wowza Media Systems\Wowza Streaming Engine (버전)\lib
Step 3 : 와우자 서비스 재시작
와우자 서비스를 재시작해 주면, 와우자가 재기동되면서 라이브러리 디렉토리의 JAR 파일들을 적재한다.
설치 작업 자체는 이것으로 끝이다. 이어서 와우자가 이 모듈을 어디에서 어떻게 사용할지 정해주면 된다.
와우자 스트리밍 엔진 확장 모듈 적용 방법
와우자 모듈은 와우자 서버 레벨에서 실행되거나 와우자의 하위 어플리케이션 레벨에서 실행될 수 있다.
서버 레벨
와우자 서버 전체를 대상으로 동작하며, 여러 어플리케이션에서 공통으로 사용하거나 서버가 시작될 때부터 실행해야 하는 기능인 경우가 많다. 등록 위치는 보통 Server Listener, HTTP Provider 또는 서버 전역 설정에 위치하며, 설정을 변경한 뒤에는 보통 와우자 서비스 자체를 재시작해야 한다.
어플리케이션 레벨
등록한 어플리케이션과 해당 인스턴스를 대상으로 동작하며, 특정 스트림의 처리, 접속 제어, 녹화, 복제처럼 서비스나 스트림별 단위로 동작하는 기능인 경우가 많다. 보통 해당 어플리케이션의 Modules와 Properties에 등록하고, 설정을 저장한 뒤 해당 어플리케이션만 재시작해 적용할 수 있다.
여기에서는 어플리케이션 레벨에서 동작하는 wse-plugin-duplicatestreams 모듈을 예로 설치한 모듈을 적용하는 방법을 설명한다.
와우자 엔진 매니저 웹 UI에 접속해 모듈을 적용할 어플리케이션을 선택한 뒤 Modules 항목으로 이동한다.
와우자 어플리케이션의 모듈 목록
모듈 이름과 클래스명 입력
Add Module 버튼을 클릭해 Add New Module 창을 띄운 후 모듈의 이름과 클래스명을 입력한다.
모듈 정보를 입력하는 모습
Name
모듈을 구분할 수 있는 이름을 입력한다. 같은 어플리케이션에 등록된 다른 모듈의 이름과 중복되지 않아야 한다.
Description
모듈에 대한 추가 설명을 입력한다.
Fully Qualified Class Name
모듈을 호출하기 위한 완전한 클래스명을 입력한다. 각 모듈의 공식 배포 문서나 README에 명시된 클래스명을 정확하게 입력해야 한다.
어플리케이션 재시작어플리케이션에 모듈이 추가된 모습
Add 버튼과 Save 버튼을 클릭해 모듈 목록 화면으로 돌아오면 어플리케이션의 모듈 목록 제일 아래에 추가한 모듈의 정보가 표시되고 재시작 버튼이 활성화된다. Restart Now 버튼을 클릭해 어플리케이션을 재실행한다.
어플리케이션의 속성값들을 입력하기 위해 Properties를 선택해 설정 메뉴로 진입한다.
어플리케이션의 Properties 설정 화면
제일 아래에 위치한 Custom 섹션으로 이동하여 수정을 위해 Edit 버튼을 클릭한다.
어플리케이션의 Custom Property 목록
Add Custom Property 버튼을 클릭해 확장 모듈에 사용할 설정값을 추가해 준다. 한 번에 하나의 속성만을 추가해 줄 수 있다. 여러 속성을 추가해야 할 경우 반복해서 추가해 준다.
Custom Property를 추가하는 모습
모든 속성을 추가했으면 Save 버튼을 클릭해 저장한다.
모듈의 속성이 추가된 모습
이어서 어플리케이션을 재시작하고 복제된 스트림이 생성되는지 확인한다. 정상적으로 동작하지 않으면 와우자 로그에서 클래스 로드 오류, 모듈 초기화 오류와 프로퍼티 설정값을 확인한다.
FAQ
사용자도 와우자 스트리밍 엔진용 자바 모듈을 만들 수 있는가?
가능하다. 자바와 와우자 스트리밍 엔진의 Java API에 대한 지식이 있다면, 스트림 처리, 접속 제어, 자동 녹화, 외부 시스템 연동처럼 사용자가 원하는 기능을 직접 개발해 모듈로 적용할 수 있다. 개발한 모듈은 일반적으로 JAR 파일로 빌드해 와우자 엔진의 라이브러리 디렉토리에 배치한 뒤, 서버 또는 어플리케이션 설정에 등록해 사용한다.
JAR 파일을 직접 생성해야 하는 경우는?
대부분의 모듈은 배포자가 제공하는 JAR 파일을 그대로 사용할 수 있다. 다만 제공된 JAR 파일이 현재 사용 중인 와우자 스트리밍 엔진, Java 런타임 또는 의존 라이브러리 버전과 호환되지 않거나 소스 코드만 제공되는 경우에는 소스를 내려받아 직접 빌드해야 한다. 직접 빌드할 때는 사용 중인 와우자 엔진과 Java 버전에 맞는 개발 환경을 구성해야 한다.
서버 레벨 기능은 와우자 엔진 전체를 대상으로 동작하며, Server Listener, HTTP Provider 또는 서버 전역 설정에 등록하는 경우가 많다. 서버 레벨 설정을 변경하면 일반적으로 와우자 엔진 서비스 전체를 재시작해야 한다. 어플리케이션 레벨 모듈은 등록한 어플리케이션과 해당 인스턴스를 대상으로 동작하며, Modules와 Properties 설정을 변경한 뒤 해당 어플리케이션만 재시작해 적용할 수 있다. 다만 새 JAR 파일을 추가하거나 교체한 경우에는 서버 전체 재시작이 필요할 수 있다.
모든 확장 모듈을 서버 레벨과 어플리케이션 레벨 중에서 자유롭게 선택해 설치할 수 있는가?
아니다. 혼용해 사용할 수 있는 모듈도 있지만 대부분 적용 위치가 정해져 있다. 어플리케이션 모듈을 Server Listener처럼 등록하거나 서버 레벨 기능을 어플리케이션의 Modules에 등록하면 정상적으로 동작하지 않는다. 따라서 배포 문서의 설치 위치, 클래스명과 설정 방법을 그대로 따라야 한다.
와우자 스트리밍 엔진에 모듈을 등록할 때 주의해야 할 사항은?
Fully Qualified Class Name과 프로퍼티 이름은 대소문자와 철자를 정확히 입력해야 한다. 클래스명이나 키 값에 오타가 있어도 관리자 화면에서 즉시 오류가 표시되지 않을 수 있으므로 공식 README의 값을 복사·붙여넣기 하는 것이 안전하다. 설정을 저장한 뒤에는 적용 범위에 따라 어플리케이션 또는 와우자 엔진을 재시작해야 한다.
Fully Qualified Class Name이란?
패키지 경로를 포함한 자바 클래스의 전체 이름이다. 예를 들어 com.wowza.wms.plugin.ModuleDuplicateStreams처럼 입력하며, 와우자 엔진은 이 값을 이용해 JAR 파일 안에서 실행할 클래스를 찾는다. 클래스명이 실제 JAR 파일의 클래스와 일치하지 않으면 모듈이 로드되지 않는다.
확장 모듈의 속성인 프로퍼티(Property)는 어떤 역할을 하는가?
프로퍼티는 확장 모듈의 세부 동작을 결정하는 설정값이다. 대상 스트림 이름, 적용할 어플리케이션, 최대 접속자 수, 파일 경로처럼 모듈마다 서로 다른 값을 지정할 수 있다. 프로퍼티의 이름, Path, Type 또는 Value가 잘못되면 모듈이 실행되더라도 의도한 기능이 동작하지 않을 수 있다.
Custom Property의 Path와 Type도 정확하게 입력해야 하는가?
그렇다. 같은 이름의 프로퍼티라도 잘못된 Path에 등록하면 모듈이 해당 값을 찾지 못할 수 있다. 또한 문자열, 숫자, Boolean처럼 모듈에서 요구하는 Type과 실제 입력 형식이 일치해야 한다. 배포 문서에 지정된 Path, Name, Type과 Value 형식을 그대로 적용하는 것이 좋다.
같은 모듈의 여러 버전 JAR 파일을 함께 설치해도 되는가?
권장하지 않는다. 동일한 클래스를 포함한 구버전과 신버전 JAR 파일이 라이브러리 디렉토리에 함께 있으면 어떤 클래스가 로드될지 불명확해지거나 클래스 충돌이 발생할 수 있다. 모듈을 교체할 때는 기존 JAR 파일을 백업한 뒤 제거하고, 사용할 버전 하나만 남기는 것이 안전하다.
JAR 파일을 복사한 뒤 어플리케이션만 재시작하면 되는가?
새 JAR 파일을 추가하거나 기존 JAR 파일을 교체했다면 와우자 엔진 서비스를 전체 재시작하는 것이 안전하다. JAR 파일은 서버 기동 과정에서 클래스 경로에 로드되기 때문이다.
모듈이 정상적으로 로드되었는지는 어떻게 확인하는가?
관리자 화면에서 모듈 등록 여부만 확인하지 말고 실제 기능을 시험해야 한다. 문제가 있으면 와우자 로그에서 ClassNotFoundException, NoClassDefFoundError, NoSuchMethodError, 프로퍼티 누락이나 초기화 오류가 기록되었는지 확인한다. 모듈이 생성해야 하는 스트림, 파일 또는 응답이 실제로 나타나는지도 함께 점검해야 한다.
모듈 설치 후 와우자 엔진이 시작되지 않으면 어떻게 해야 하는가?
새로 추가한 JAR 파일과 설정을 우선 원래 상태로 되돌린 뒤 엔진을 다시 시작한다. 이후 로그에서 Java 버전 불일치, 의존 라이브러리 누락, 클래스 충돌, 클래스명 오타와 설정 파일 오류를 확인한다. 운영 환경에서는 설치 전에 기존 JAR 파일과 관련 설정을 반드시 백업하는 것이 좋다.
와우자 확장 모듈을 사용하려면 자바 지식이 필요한가?
이미 빌드된 모듈을 설치하고 사용하는 데에는 깊은 자바 개발 지식이 반드시 필요한 것은 아니다. 배포 문서에 따라 JAR 파일을 복사하고 클래스명과 프로퍼티를 정확히 등록할 수 있다면 대부분 사용할 수 있다. 다만 오류 원인을 분석하거나 모듈을 수정·개발하려면 자바, 와우자 API와 서버 로그에 대한 이해가 필요하다.
서드파티 확장 모듈을 설치할 때 확인해야 할 사항은?
배포자의 신뢰도, 최근 업데이트 시점, 지원하는 와우자 엔진과 Java 버전, 소스 공개 여부, 라이선스와 알려진 오류를 확인해야 한다. 운영 서버에 바로 적용하지 말고 시험 환경에서 기능과 안정성을 검증한 뒤 배포하는 것이 좋다.
