사용자들이 서로를 보고 상호작용할 수 있을 때 모든 앱은 더 재미있어집니다. 특히 Unity를 사용할 때는 옵션이 제한적입니다. 제가 발견한 비디오 스트리밍을 위한 최고의 애플리케이션 개발 솔루션은 Unity Asset Store를 통해 제공되는 Agora Video SDK for webRTC 채팅 Unity입니다.
이 가이드에서는 크로스플랫폼 Unity 스트림 비디오 채팅 모바일 앱을 구축하기 위해 필요한 모든 단계를 단계별로 안내합니다.
필수 조건
- Unity Editor
- Unity Editor, 게임 오브젝트, Unity 스크립팅, 모바일 기기에 Unity 앱을 배포하는 방법에 대한 이해
- C# 언어에 대한 기본 이해
- Agora 개발자 계정
참고: Unity 지식이 없어도 따라할 수 있지만, 특정 기본 개념(필수 조건 참조)은 설명되지 않습니다.
개요
유니티 스트림 비디오 앱을 만들기 전에, 우리가 진행할 모든 단계를 간단히 살펴보겠습니다:
새 프로젝트 설정
먼저 Unity를 열고 새 프로젝트를 생성한 후 이름을 “Agora Video Demo”로 지정합니다. Unity가 프로젝트 설정을 완료하면 Unity Asset Store로 이동하여 “Agora Video SDK”를 검색합니다. 다음으로 Unity용 Agora Video SDK를 프로그램에 임포트합니다. 창이 표시되면 목록에 있는 모든 자산을 선택했는지 확인합니다.
장면 생성
이제 새로운 장면을 생성하고 이름을 WelcomeScene로 지정합니다. 장면을 두 번 클릭하여 에디터 뷰에서 열습니다. WelcomeScene는 Unity 비디오 플레이어 라이브 스트림이 로드될 때 사용자가 처음 보는 화면이 됩니다. 시작하기 위해 장면에서 기존 카메라와 조명을 제거하겠습니다. 먼저 Canvas 게임 오브젝트를 추가합니다. 다음으로 Canvas의 자식 오브젝트로 Camera를 추가합니다. 화면이 2D로 표시되도록 하기 위해 Unity가 카메라에서 비디오를 스트리밍할 때 동일한 모드로 표시되도록 에디터를 2D 모드로 전환합니다. 또한 에디터 뷰를 게임 모드로 전환하여 카메라 뷰에 대한 오브젝트의 위치를 시각화할 수 있도록 합니다.
채팅에 참여하도록 앱을 트리거할 버튼이 필요하므로 버튼을 추가하고 이름을 JoinChannel 로 지정하며 레이블을 추가합니다. 버튼의 크기 및 위치를 조정합니다. 사용자가 채널 이름을 입력할 수 있도록 텍스트 입력 필드를 생성하고 이름을 ChannelName 로 지정하며 의미 있는 플래시홀더 텍스트를 추가합니다. 앱에 대한 간단한 설명을 추가하기 위해 텍스트 상자를 추가합니다. 캔버스의 자식 객체로 텍스트 게임 오브젝트를 생성합니다. 아래는 제가 작성한 텍스트이지만, 원하는 메시지를 자유롭게 추가해 주세요.
Agora Video SDK for Unity 예제는 Agora Gaming SDK를 사용하여 게임 장면에 비디오 콘텐츠를 통합하는 방법을 보여줍니다.
이 예제는 1대1 Unity 스트림 비디오 통신을 지원합니다. 두 기기는 동일한 모드와 채널을 선택하여 서로 통신할 수 있습니다. 로컬 미리보기 영상은 3D 오브젝트에 렌더링되며, 원격 영상은 Plane에 렌더링됩니다.
각 오브젝트의 위치를 조정하여 충분한 공간을 확보하도록 잠시 시간을 내어 조정해 보겠습니다.
다음으로 새로운 장면을 생성하고 이름을 ChatScene로 지정합니다. 이 장면은 로컬 및 원격 비디오 스트림이 재생되는 화면이 됩니다. Agora Video SDK의 일부 기능을 테스트해 보려면 장면에 몇 가지 모양을 추가해 보겠습니다. 먼저 장면에 정육면체를 추가해 보겠습니다. 장면에 3D 요소가 포함되어 있으므로 편집기의 2D 모드를 종료합니다. 이제 정육면체를 더 잘 볼 수 있지만 크기가 작아 보이므로 모든 축의 스케일을 2로 변경합니다.
큐브가 로컬 카메라 스트림을 텍스처로 렌더링하도록 하려면 VideoSurface.cs를 큐브의 컴포넌트로 추가해야 합니다. 실린더 게임 오브젝트를 추가해 보겠습니다. 먼저 큐브에 가려지지 않도록 위쪽으로 이동합니다. 다음으로 실린더에 고유한 스케일을 설정하고, VideoSurface.cs를 컴포넌트로 추가합니다.
마지막으로 장면에 캔버스를 추가하겠습니다. 이 캔버스를 통해 채팅을 나가기 위한 2D 버튼을 추가할 수 있습니다. 이 버튼을 LeaveButton (매우 창의적)이라고 이름 짓고 적절한 라벨을 부여하겠습니다. 이 과정에서 텍스트 상자를 추가하고 VersionText라고 이름 짓겠습니다. 이 텍스트 상자는 나중에 시스템이 정상적으로 작동하는지 시각적으로 확인하는 데 사용할 수 있습니다. VersionText를 화면 오른쪽 상단 모서리에 배치하여 방해되지 않도록 하고, 색상을 흰색으로 설정하여 쉽게 볼 수 있도록 합니다.
버튼 터치 처리
장면을 설정하는 과정에서 두 개의 버튼(JoinButton과 LeaveButton)을 생성했기 때문에, 이제 이 버튼들에 특정 동작을 연결하는 스크립트를 생성해야 합니다.
자산에 새로운 C# 스크립트를 생성합니다. 이름을 ButtonHandler.cs로 지정하고 Visual Studio에서 파일을 열기 위해 두 번 클릭합니다. 함수 OnButtonClick()를 추가하고, 단순화를 위해 함수 본문에 디버그 로그를 추가합니다.
Debug.Log(“Button Clicked: “ + name);Unity의 WelcomeScene로 돌아가서 스크립트와 함수를 버튼에 연결합니다. 먼저 JoinButton을 선택하고 ButtonHandler스크립트를 컴포넌트로 추가합니다. 다음으로 이벤트를 추가하고 버튼 클릭을 OnButtonClick()에 매핑합니다. 이 과정을 ChatScene 내의 LeaveButton에 대해 반복합니다.
이제 두 개의 버튼이 동일한 기능을 호출하도록 설정되었으니, 두 버튼을 구분하기 위한 논리를 추가해 보겠습니다. Agora 구현을 위해 ChannelName 필드에서 사용자 입력을 받기 위해 몇 줄의 코드를 추가하겠습니다. 먼저 UI 라이브러리를 포함해야 하며, 그 다음 ChannelName 게임 오브젝트에서 InputField 컴포넌트를 가져올 수 있습니다.
아고라 SDK 구현
먼저 자산 폴더에 새로운 C# 스크립트를 생성하고 이름을 AgoraInterface.cs로 지정합니다. 해당 파일을 Visual Studio에서 열습니다. 첫 번째로 생성할 변수는 appId이며, 이 변수는 Agora 앱 ID를 저장합니다. 잠시 시간을 내어 Agora 개발자 계정에 로그인한 후 개인 App ID를 복사하여 appId의 값에 붙여넣습니다.Agora RTC 엔진에 대한 참조를 저장할 변수와 원격 스트림의 ID를 위한 임시 변수도 생성해야 합니다.
private static string appId = "Agora App ID";
public IRtcEngine mRtcEngine;
public uint mRemotePeer;참고: 아고라 개발자 계정이 없다면, 설정 과정을 안내하는 빠른 튜토리얼을 작성했습니다.
아고라 RTC 엔진을 초기화하는 함수를 만들어 보겠습니다. 이 함수를 LoadEngine()라고 명명하겠습니다. 엔진이 이미 존재하지 않는 경우에만 한 번만 초기화되도록 해야 합니다. 엔진이 존재하지 않는 경우, IRtcEngine.getEngine(appId)¹를 호출하여 Agora 앱 ID를 전달합니다.
여기서 로그 수준을 Debug로 설정할 수 있습니다. 이렇게 하면 디버그 로그를 확인하고 모든 것이 예상대로 작동하는지 확인할 수 있습니다. 지금까지 보셨듯이, 저는 실행 중 발생하는 상황을 명확히 이해하기 위해 많은 디버그 로그를 추가하는 것을 선호합니다.
다음으로 JoinChannel() 함수를 선언합니다. 먼저 RTC 엔진이 존재하는지 확인한 후 EnableVideo를 호출하고 VideoObserver를 활성화합니다. 마지막으로 ChannelName을 사용하여 JoinChannel를 호출합니다.
현재까지 Agora RTC 엔진을 초기화하고 채널에 가입하는 방법을 구현했지만, 이제 사용자가 채널을 떠나고 엔진을 “unload”하는 방법을 추가해야 합니다. LeaveChannel()로 시작합니다. 다시 엔진이 존재하는지 확인한 후 엔진을 사용하여 leaveChannel()를 호출하고 DisableVideoObserver()를 호출합니다. 마지막으로 엔진을 언로드하기 위해 IRtcEngine.Destroy()를 호출하고 로컬 참조를 null로 설정합니다.
엔진의 기본 라이프사이클 이벤트가 모두 처리되었으므로, 이제 엔진이 다양한 사전 정의된 이벤트에 따라 호출할 수 있는 콜백 함수를 추가할 준비가 되었습니다. 이 구현에서는 세 가지 콜백 함수에 집중할 것입니다: OnChannelJoinSuccess, OnUserJoined, 및 OnUserOffline.
OnChannelJoinSuccess는 로컬 기기가 채널에 성공적으로 연결될 때마다 호출됩니다; OnUserJoined는 원격 스트림이 채널에 연결될 때마다 호출됩니다; OnUserOffline 는 원격 스트림이 채널을 떠날 때마다 호출됩니다. 각 함수를 정의한 후, 편집기가 43–45행의 오류에 대해 더 이상 경고하지 않는 것을 확인할 수 있습니다.
현재는 OnChannelJoinSuccess 함수를 로그만 남기고 남겨두겠습니다. 나중에 다시 살펴보겠습니다.
OnUserJoined 함수 내에서는 Empty Game Object를 생성하고 이를 Plane으로 초기화하는 논리를 추가합니다. Game Object의 이름을 원격 스트림의 uid로 설정하여 나중에 쉽게 참조할 수 있도록 합니다. 이 평면을 원격 스트림을 렌더링하는 데 사용하려면 Game Object에 VideoSurface 컴포넌트를 추가하고, VideoSurface를 원격 스트림의 uid로 설정하며, setEnable(true)를 사용하여 평면에서 렌더링을 활성화합니다. 비디오 Plane이 고정되지 않도록 예시로, Plane의 스케일을 설정하고 y축 방향으로 임의의 위치에 배치합니다. TransformDelegate를 VideoSurface에 추가하면 update()에서 호출되어 Plane이 x축 주변으로 회전하는 것을 확인할 수 있습니다.
OnUserOffline 내의 콜백을 완료하기 위해, OnUserJoined 내에서 생성된 게임 오브젝트를 파괴하는 논리를 추가합니다.
TransformDelegate 함수를 추가하여 이 함수를 호출하는 모든 Game Object의 모양을 왜곡하고 회전하도록 하겠습니다. TransformDelegate 내부에 uid == 0 인 경우의 논리를 추가했음을 알아차리셨을 것입니다. 이는 VideoSurface의 로컬 스트림에 TransformDelegate를 호출할 때만 true가 됩니다. OnChatSceneLoaded라는 함수를 선언하고, 그 안에 Cylinder의 VideoSurface에 TransformDelegate를 설정하는 논리를 추가해 보겠습니다. 이제 ButtonHandler.cs 스크립트로 돌아가서 ChatScene가 로딩이 완료되면 OnChatLoaded 함수를 호출하는 논리를 추가해 보겠습니다.
장치에서 작업을 테스트하기 전에 Android용 권한 요청을 추가해야 합니다. Unity 2018_3부터 보안 목적으로 권한이 자동으로 추가되지 않기 때문에 마이크와 카메라 권한을 확인하고 요청하는 몇 가지 if-else 문장을 추가해야 합니다.
마지막으로, 채널에 성공적으로 연결될 때마다 VersionText를 채우는 논리를 추가해 보겠습니다. 이를 위해 AgoraInterface.cs 스크립트로 돌아가서 getSDKVersion 함수를 선언합니다. 이 함수는 Agora RTC 엔진에서 SDK 버전을 반환합니다. 이제 이 함수를 이전에 생성한 OnChannelJoinSuccess 이벤트 핸들러와 연결해 보겠습니다. VersionText 게임 오브젝트를 찾아 텍스트를 “Version: ” + getSdkVersion()로 설정합니다.
기기에서 빌드 및 테스트 (iOS 및 Android)
이제 앱을 테스트해 볼 때입니다! Unity로 돌아가서 Build Settings를 엽니다. 먼저 WelcomeScene와 ChatScene를 Build Settings 대화 상자의 Scene 목록으로 드래그합니다.
앱을 빌드하고 배포하기 전에 각 플랫폼의 Player Settings를 조정해야 합니다. Platform 목록에서 iOS를 선택하고 Player Settings를 엽니다. 먼저 Auto Graphics API 옵션을 해제합니다. 다음으로 Graphics API 옵션 내에서 목록에 OpenGLES2만 남아 있는지 확인합니다(필요시 + 아이콘을 사용하여 추가해야 할 수 있습니다) 다른 API는 모두 제거합니다. 또한 Multithreaded Rendering 옵션을 선택 해제합니다. Bundle ID를 업데이트하고 카메라 및 마이크 사용 설명에 텍스트를 입력합니다(권한 요청을 활성화합니다).
이제 앱을 빌드할 준비가 되었습니다! Build Settings 대화상자에서 Build 버튼을 클릭하면 Unity가 빌드를 저장할 위치를 묻습니다. 저는 파일을 정리하기 위해 Builds 폴더를 생성하는 것을 선호합니다. 새로 생성된 Builds 폴더에 빌드를 저장하고, 빌드를 iOS로 저장합니다. Unity가 iOS 앱 빌드를 완료하면 Finder 창이 열리며 Unity-iPhone.xcodeproj파일이 표시됩니다. 이 파일을 두 번 클릭하여 Xcode를 열습니다. Xcode가 열리면 왼쪽 파일 탐색기에서 프로젝트를 선택하고 자동 서명을 활성화한 후 팀 프로필을 선택합니다. 마지막으로 테스트 기기가 연결되어 있는지 확인한 후 Play 버튼을 클릭합니다.
WelcomeScene가 먼저 로드되는 것을 확인할 수 있습니다. 채널에 가입하면 ChatScene로 이동하며, Leave 버튼을 클릭하면 다시 WelcomeScene로 돌아갑니다. 유일하게 부족한 것은 원격 스트림이지만, 이를 위해 두 번째 기기가 필요합니다.
이 시점에서 다른 iOS 기기를 연결하고 Unity 스트림 비디오 데모 앱을 다시 실행할 수 있지만, 이는 재미がありません. 따라서 Unity로 돌아가서 안드로이드용 프로젝트를 빌드해 보겠습니다.
Platform 목록에서 Android를 선택하고 iOS와 동일한 단계를 따릅니다. Player Settings를 열고 OpenGLES2를 사용 중인지 확인한 후 Multithreaded Rendering 옵션을 비활성화하고 Package ID를 입력합니다.
안드로이드 기기가 충전 중인지 확인한 후 빌드 및 실행을 클릭하세요. Unity는 프로젝트를 저장하라는 메시지를 표시합니다. 저는 빌드 이름을 Android로 지정했습니다.
완료!
유니티 비디오 스트리밍 앱을 성공적으로 만들었습니다. 큰 성과를 거두셨으니 스스로를 칭찬해 주세요! 잘하셨습니다!! 함께 따라해 주셔서 감사합니다. 질문이 있으시면 아래에 댓글을 남겨주시거나, Agora의 서비스에 대해 더 알고 싶으시면 언제든지 연락해 주세요!
참고: 이 단계에서 iOS 앱과 Android 앱을 실행하여 채널에서 로컬 및 원격 스트림을 모두 확인할 수 있습니다.
기타 리소스
- The Agora Video SDK for Unity는 Unity Asset Store에서 사용할 수 있습니다.
- 완전한 API 문서서는 Document Center에서 확인할 수 있습니다.
- 기술 지원이 필요하시면 Agora 대시보드를 통해 티켓을 제출해 주세요.
각주
- 왜
getEngine()를 사용해야 하는지 궁금해하실 수 있습니다.new IRtcEngine()대신에 말이죠. 이는 아고라의 RTC 엔진이 싱글턴으로 작동하기 때문입니다.getEngine()는 인스턴스가 존재하는지 확인하고 존재하지 않으면 새로운 인스턴스를 생성합니다.getEngine()함수는 코드의 다른 부분에서 엔진에 대한 참조를 얻기 위해 나중에 다시 호출될 수 있습니다. - 모든 콜백은
AgoraGameRtcEngine.cs - (Assets → /Scripts → /AgoraGamingSDK)
참고: 각 콜백 함수는 특정 매개 변수 세트를 전달하므로 다른 콜백을 추가할 계획이라면 AgoraGameRtcEngine.cs 파일을 확인하는 것이 중요합니다.
