jsm.extension 1.0.2

jsm.extension

jsm.standard의 확장 라이브러리입니다. .NET 8.0 기반의 고급 기능을 제공하며, SignalR을 통한 실시간 통신과 음성 통화 기능을 포함합니다.

주요 기능

🔌 SignalR 서버/클라이언트

• SignalR 서버: ASP.NET Core 기반의 실시간 통신 서버
• SignalR 클라이언트: 서버에 연결하여 실시간 메시지 송수신
• Hub 구현: JSBotHub - 사용자 관리, 메시지 브로드캐스팅, 그룹 관리
• 연결 관리: 자동 재연결, 연결 상태 모니터링

📞 음성 통화 (VoiceCall)

• 실시간 음성 통화: NAudio 기반의 고품질 음성 통신
• 양방향 통화: 실시간 오디오 스트리밍
• 통화 상태 관리: 발신, 수신, 통화 중, 종료 상태 관리
• 이벤트 기반: 통화 상태 변경 이벤트 지원

설치

.NET CLI

dotnet add package jsm.extension

Package Manager Console

Install-Package jsm.extension

PackageReference

<ItemGroup>
  <PackageReference Include="jsm.extension" Version="1.0.0" />
</ItemGroup>

참고: jsm.extension은 jsm.standard에 의존하므로 자동으로 설치됩니다.

빠른 시작

SignalR 서버 시작

using jsm.extension.SignalR;

// 서버 생성 및 시작
var server = new SignalRServer("http://localhost:5000");
await server.StartAsync();

Console.WriteLine($"SignalR 서버가 시작되었습니다: {server.Url}");
Console.WriteLine("Hub 엔드포인트: /jsbothub");

// 서버 중지
await server.StopAsync();

SignalR 클라이언트 연결

using jsm.extension.SignalR;

// 클라이언트 생성 및 연결
var client = new SignalRClientManager("http://localhost:5000/jsbothub");

// 연결 이벤트 핸들러
client.OnConnected += () => Console.WriteLine("연결되었습니다!");
client.OnDisconnected += () => Console.WriteLine("연결이 끊어졌습니다.");
client.OnMessageReceived += (message) => Console.WriteLine($"메시지 수신: {message}");

// 연결
await client.ConnectAsync();

// 사용자 이름 설정
await client.SetUserNameAsync("사용자1");

// 메시지 전송
await client.SendMessageAsync("Hello, SignalR!");

// 채팅 메시지 전송
await client.SendChatMessageAsync("안녕하세요!");

// 연결 종료
await client.DisconnectAsync();

음성 통화 사용

using jsm.extension.VoiceCall;
using jsm.extension.SignalR;

// SignalR 클라이언트 생성
var signalRClient = new SignalRClientManager("http://localhost:5000/jsbothub");
await signalRClient.ConnectAsync();
await signalRClient.SetUserNameAsync("사용자1");

// VoiceCall 매니저 생성
var voiceCallManager = new VoiceCallManager(signalRClient);

// 통화 상태 변경 이벤트
voiceCallManager.CallStateChanged += (sender, e) =>
{
    Console.WriteLine($"통화 상태 변경: {e.State}");
    if (e.TargetUserName != null)
    {
        Console.WriteLine($"대상: {e.TargetUserName}");
    }
};

// 통화 시작 (대상 사용자의 Connection ID 필요)
string targetConnectionId = "대상의 Connection ID";
await voiceCallManager.StartCallAsync(targetConnectionId);

// 통화 종료
await voiceCallManager.EndCallAsync();

주요 클래스

SignalR 네임스페이스

SignalRServer

SignalR 서버를 구현하는 클래스입니다.

주요 메서드:

• StartAsync() - 서버 시작
• StopAsync() - 서버 중지
• BroadcastMessageAsync(string message) - 모든 클라이언트에 메시지 브로드캐스트

속성:

• IsRunning - 서버 실행 상태
• Url - 서버 URL

SignalRClientManager

SignalR 클라이언트를 관리하는 클래스입니다.

주요 메서드:

• ConnectAsync() - 서버에 연결
• DisconnectAsync() - 연결 종료
• SetUserNameAsync(string userName) - 사용자 이름 설정
• SendMessageAsync(string message) - 메시지 전송
• SendChatMessageAsync(string message) - 채팅 메시지 전송
• SendToClientAsync(string connectionId, string message) - 특정 클라이언트에 메시지 전송
• JoinGroupAsync(string groupName) - 그룹 참가
• LeaveGroupAsync(string groupName) - 그룹 탈퇴

이벤트:

• OnConnected - 연결 완료 시 발생
• OnDisconnected - 연결 종료 시 발생
• OnMessageReceived - 메시지 수신 시 발생
• OnChatMessageReceived - 채팅 메시지 수신 시 발생
• OnUserJoined - 사용자 참가 시 발생
• OnUserLeft - 사용자 나감 시 발생

JSBotHub

SignalR Hub 구현 클래스입니다. 서버 측에서 사용됩니다.

주요 메서드:

• SetUserName(string userName) - 사용자 이름 설정
• SendMessage(string message) - 메시지 전송
• SendChatMessage(string message) - 채팅 메시지 전송
• SendToClient(string connectionId, string message) - 특정 클라이언트에 메시지 전송
• SendToGroup(string groupName, string message) - 그룹에 메시지 전송
• JoinGroup(string groupName) - 그룹 참가
• LeaveGroup(string groupName) - 그룹 탈퇴

VoiceCall 네임스페이스

VoiceCallManager

음성 통화를 관리하는 클래스입니다.

주요 메서드:

• StartCallAsync(string targetConnectionId) - 통화 시작
• AnswerCallAsync(string callerConnectionId, bool accept) - 통화 수락/거절
• EndCallAsync() - 통화 종료
• SendAudioDataAsync(string targetConnectionId, byte[] audioData) - 오디오 데이터 전송

속성:

• CurrentState - 현재 통화 상태 (Idle, Calling, Ringing, InCall)
• CurrentCallTarget - 현재 통화 대상 사용자 이름

이벤트:

• CallStateChanged - 통화 상태 변경 시 발생

AudioManager

오디오 입력/출력을 관리하는 클래스입니다. 내부적으로 사용됩니다.

상세 사용 예제

SignalR 서버 설정

using jsm.extension.SignalR;
using Microsoft.Extensions.DependencyInjection;

var server = new SignalRServer("http://localhost:5000");

// 서버 시작
await server.StartAsync();

// Hub 컨텍스트를 통한 메시지 브로드캐스트
await server.BroadcastMessageAsync("서버에서 보내는 메시지");

// 서버 중지
await server.StopAsync();

클라이언트 간 통신

using jsm.extension.SignalR;

// 클라이언트 1
var client1 = new SignalRClientManager("http://localhost:5000/jsbothub");
await client1.ConnectAsync();
await client1.SetUserNameAsync("Alice");

// 클라이언트 2
var client2 = new SignalRClientManager("http://localhost:5000/jsbothub");
await client2.ConnectAsync();
await client2.SetUserNameAsync("Bob");

// 클라이언트 1이 클라이언트 2에게 메시지 전송
string bobConnectionId = client2.ConnectionId; // 실제로는 서버에서 가져와야 함
await client1.SendToClientAsync(bobConnectionId, "Hello, Bob!");

// 클라이언트 2가 메시지 수신
client2.OnMessageReceived += (message) =>
{
    Console.WriteLine($"받은 메시지: {message}");
};

그룹 기능 사용

using jsm.extension.SignalR;

var client = new SignalRClientManager("http://localhost:5000/jsbothub");
await client.ConnectAsync();

// 그룹 참가
await client.JoinGroupAsync("room1");

// 그룹에 메시지 전송 (서버 측에서만 가능)
// 클라이언트에서는 일반 메시지 전송 사용

// 그룹 탈퇴
await client.LeaveGroupAsync("room1");

통화 기능 상세 사용

using jsm.extension.VoiceCall;
using jsm.extension.SignalR;

var signalRClient = new SignalRClientManager("http://localhost:5000/jsbothub");
await signalRClient.ConnectAsync();
await signalRClient.SetUserNameAsync("사용자1");

var voiceCall = new VoiceCallManager(signalRClient);

// 통화 상태 모니터링
voiceCall.CallStateChanged += (sender, e) =>
{
    switch (e.State)
    {
        case CallState.Idle:
            Console.WriteLine("통화 대기 중");
            break;
        case CallState.Calling:
            Console.WriteLine($"통화 시도 중: {e.TargetUserName}");
            break;
        case CallState.Ringing:
            Console.WriteLine($"통화 수신 중: {e.TargetUserName}");
            break;
        case CallState.InCall:
            Console.WriteLine($"통화 중: {e.TargetUserName}");
            break;
    }
};

// 통화 시작
string targetConnectionId = "대상 Connection ID";
await voiceCall.StartCallAsync(targetConnectionId);

// 통화 수락 (수신 측)
string callerConnectionId = "발신자 Connection ID";
await voiceCall.AnswerCallAsync(callerConnectionId, accept: true);

// 통화 종료
await voiceCall.EndCallAsync();

요구사항

• .NET 8.0 이상
• ASP.NET Core (서버 기능 사용 시)
• jsm.standard 패키지 (자동 설치됨)

의존성

• jsm.standard (자동 설치)
• Microsoft.AspNetCore.SignalR.Client (8.0.0)
• NAudio (2.2.1)

아키텍처

SignalR 서버

• ASP.NET Core Host 기반
• Kestrel 웹 서버 사용
• /jsbothub 엔드포인트에서 Hub 제공

SignalR 클라이언트

• 자동 재연결 지원
• 연결 상태 관리
• 이벤트 기반 메시지 처리

VoiceCall

• NAudio를 사용한 오디오 입출력
• SignalR을 통한 오디오 데이터 전송
• 실시간 양방향 통신

성능 고려사항

• 오디오 품질: 기본 샘플링 레이트 및 비트 깊이 설정 가능
• 네트워크 대역폭: 오디오 데이터는 Base64 인코딩되어 전송
• 지연 시간: 네트워크 지연에 따라 실시간 통화 품질이 달라질 수 있음

보안 고려사항

• 인증: 현재는 사용자 이름 기반 인증만 제공
• 권한 관리: 그룹 및 개별 메시지 전송 권한 관리 필요
• HTTPS 사용: 프로덕션 환경에서는 HTTPS 사용 권장

예제 프로젝트

더 많은 예제는 프로젝트의 Examples 폴더를 참조하세요.

라이선스

MIT License

관련 프로젝트

• jsm.standard - 기본 라이브러리 (필수)

기여하기

버그 리포트, 기능 제안, Pull Request를 환영합니다!

지원

문제가 발생하거나 질문이 있으시면 GitHub Issues를 통해 문의해주세요.