Java

步骤一：导入 SDK

SDK 包目录结构如下：

AliRTCSDK_Linux/
└── Java/
    ├── libs/
    │   ├── AliRtcCoreService                      # 后台服务进程（须指定绝对路径）
    │   ├── alirtc_linux_java_multiprocess.jar      # Java 层与 C++ 引擎的桥接 JAR
    │   ├── gson-2.11.0.jar                        # JSON 序列化依赖
    │   └── libAliRtcLinuxEngine.so                # SDK 完整动态库
    └── Demo/
        ├── MainTest.java                          # 功能演示示例
        └── run.sh                                 # 编译运行脚本

编译并运行示例：

cd Demo
javac -g -cp ../libs/alirtc_linux_java_multiprocess.jar:../libs/gson-2.11.0.jar \
      -encoding utf-8 MainTest.java
java -cp .:../libs/alirtc_linux_java_multiprocess.jar:../libs/gson-2.11.0.jar MainTest

运行前确保动态库可被找到：

export LD_LIBRARY_PATH=/path/to/Java/libs:$LD_LIBRARY_PATH

步骤二：实现事件回调类

实现 AliRTCLinuxEngineListener 接口，用于接收 SDK 推送的各类通知。

import com.alivc.rtc.multiprocess.AliRTCLinuxEngine;
import com.alivc.rtc.multiprocess.AliRTCLinuxEngineListener;

class VideoCallEventHandler implements AliRTCLinuxEngineListener {

    @Override
    public void onJoinChannelResult(int result, String channel, String userId) {
        if (result == 0) {
            System.out.printf("[onJoinChannelResult] User %s joined channel %s successfully%n",
                    userId, channel);
        } else {
            System.out.printf("[onJoinChannelResult] Failed to join, error: %d%n", result);
        }
    }

    @Override
    public void onRemoteUserOnLineNotify(String uid) {
        System.out.printf("[onRemoteUserOnLineNotify] uid: %s%n", uid);
    }

    @Override
    public void onRemoteUserOffLineNotify(String uid) {
        System.out.printf("[onRemoteUserOffLineNotify] uid: %s%n", uid);
    }

    @Override
    public void onRemoteTrackAvailableNotify(String uid,
            AliRTCLinuxEngine.AudioTrack audioTrack,
            AliRTCLinuxEngine.VideoTrack videoTrack) {
        System.out.printf("[onRemoteTrackAvailableNotify] uid: %s, audio: %s, video: %s%n",
                uid, audioTrack, videoTrack);
    }

    // onSubscribeMixedAudioFrame: 接收混音后的远端 PCM 音频帧
    // 订阅配置中 subscribeAudioFormat = AudioFormatMixedPcm 时触发
    @Override
    public void onSubscribeMixedAudioFrame(AliRTCLinuxEngine.AudioFrame frame) {
        if (frame != null && frame.type == AliRTCLinuxEngine.AudioFrameType.AudioFrameRawPcm) {
            AliRTCLinuxEngine.AudioPcmFrame pcmFrame = frame.pcm;

            // pcmFrame.data        PCM 数据（byte[ ]，int16_t 格式）

            // pcmFrame.channels    声道数
            // pcmFrame.sampleRates 采样率
            // 在此写入文件、送入音频设备或解码播放
        }
    }

    // onSubscribeAudioFrame: 接收逐路远端用户的未混音 PCM 帧，uid 区分不同远端用户的音频流
    // 订阅配置中 subscribeAudioFormat = AudioFormatPcmBeforeMixing 时触发
    @Override
    public void onSubscribeAudioFrame(String uid, AliRTCLinuxEngine.AudioFrame frame) {
        if (frame != null && frame.type == AliRTCLinuxEngine.AudioFrameType.AudioFrameRawPcm) {
            AliRTCLinuxEngine.AudioPcmFrame pcmFrame = frame.pcm;
            // uid 标识该帧来自哪个远端用户
            // 在此按用户分别处理音频数据
        }
    }

    // onRemoteVideoSample: 接收远端视频帧
    // uid 区分不同远端用户的视频流
    @Override
    public void onRemoteVideoSample(String uid, AliRTCLinuxEngine.VideoFrame frame) {
        if (frame != null && frame.type == AliRTCLinuxEngine.VideoFrameType.VideoFrameH264) {
            AliRTCLinuxEngine.VideoH264Frame h264Frame = frame.h264;
            // uid 标识该帧来自哪个远端用户
            // 在此写入文件、送入渲染器或视频解码器
        }
    }

    @Override
    public void onError(int errorCode) {
        System.out.printf("[onError] error_code: 0x%X%n", errorCode);
    }
}

步骤三：鉴权 Token

Java SDK 内置 generateToken 方法，可在客户端直接生成单参数入会 Token。

Token 生成流程：

1. 拼接字符串：appId + appKey + channelId + userId + nonce + timestamp

2. SHA-256 哈希得到十六进制字符串

3. 组装 JSON：{"appid":..., "channelid":..., "userid":..., "nonce":..., "timestamp":..., "token":<sha256>}

4. Base64 编码

import java.time.Instant;

AliRTCLinuxEngine.AuthInfo authInfo = new AliRTCLinuxEngine.AuthInfo();
authInfo.appid    = "your_app_id";
authInfo.channel  = "your_channel_id";
authInfo.userid   = "your_user_id";
authInfo.username = "your_user_id";
authInfo.nonce    = null;
authInfo.timestamp = Instant.now().getEpochSecond() + 24 * 60 * 60; // 24 小时后过期

String appKey = "your_app_key"; // 生产环境请勿将 AppKey 暴露在客户端代码中

// 调用 generateToken 生成单参数入会 Token（需先创建引擎实例）
authInfo.token = engineIns.generateToken(authInfo, appKey);

步骤四：创建并初始化音视频引擎

调用 AliRTCLinuxEngine.createInstance 创建引擎实例，并传入事件回调对象。

VideoCallEventHandler listener = new VideoCallEventHandler();

String coreServicePath = "/path/to/Java/libs/AliRtcCoreService"; // 指定 AliRtcCoreService 绝对路径
boolean h5mode = false; // 与 Web 端互通请设置为 true

String extra = "{\"user_specified_disable_audio_ranking\":\"true\"}";

AliRTCLinuxEngine engineIns = AliRTCLinuxEngine.createInstance(
    listener,
    42000, 45000,   // IPC 端口范围，用于 Java 层与 AliRtcCoreService 进程通信
    "/tmp",         // 日志文件目录
    coreServicePath,
    h5mode,
    extra
);

if (engineIns == null) {
    System.err.println("Failed to create RTC engine");
    return;
}

步骤五：设置音视频属性

调用 setClientRole 设置用户角色，调用 setVideoEncoderConfiguration 配置视频编码参数。

// 调用 setClientRole 设置用户角色为互动模式（主播），可同时发布和订阅
engineIns.setClientRole(AliRTCLinuxEngine.AliEngineClientRole.AliEngineClientRoleInteractive);

// 调用 setVideoEncoderConfiguration 设置视频编码参数
AliRTCLinuxEngine.AliEngineVideoEncoderConfiguration videoConfig =
        new AliRTCLinuxEngine.AliEngineVideoEncoderConfiguration();
videoConfig.dimensions = new AliRTCLinuxEngine.AliEngineVideoDimensions(720, 1280);
videoConfig.frameRate  = AliRTCLinuxEngine.AliEngineFrameRate.AliEngineFrameRateFps15;
videoConfig.bitrate    = 1200;
engineIns.setVideoEncoderConfiguration(videoConfig);

步骤六：设置推拉流属性

配置音视频的发布和订阅行为，并启用 Linux 平台特有的外部音视频源模式。

// 调用 publishLocalVideoStream / publishLocalAudioStream 开启本地音视频发布
engineIns.publishLocalVideoStream(true);
engineIns.publishLocalAudioStream(true);

// Linux 无内置摄像头/麦克风，调用 setExternalVideoSource 启用外部视频源，
// 通过 pushExternalVideoFrame 输入 YUV 帧数据
engineIns.setExternalVideoSource(true,
        AliRTCLinuxEngine.VideoSource.VideoSourceCamera,
        AliRTCLinuxEngine.RenderMode.RenderModeFill);

// 调用 setExternalAudioSource 启用外部音频源，通过 pushExternalAudioFrameRawData 输入 PCM 帧数据
engineIns.setExternalAudioSource(true, 16000 /* 采样率 */, 1 /* 声道数 */);

配置入会时的订阅模式（在步骤七的 JoinChannelConfig 中设置）：

AliRTCLinuxEngine.JoinChannelConfig joinConfig = new AliRTCLinuxEngine.JoinChannelConfig();
joinConfig.channelProfile    = AliRTCLinuxEngine.ChannelProfile.ChannelProfileInteractiveLive;
joinConfig.publishMode       = AliRTCLinuxEngine.PublishMode.PublishAutomatically;     // 自动推流
joinConfig.subscribeMode     = AliRTCLinuxEngine.SubscribeMode.SubscribeAutomatically; // 自动订阅
joinConfig.publishAvsyncMode = AliRTCLinuxEngine.PublishAvsyncMode.PublishAvsyncWithPts;

// 音频订阅格式有两种选择：
// AudioFormatMixedPcm: 接收混音后的整频道 PCM，触发 onSubscribeMixedAudioFrame
// AudioFormatPcmBeforeMixing: 接收每个远端用户的逐路 PCM，触发 onSubscribeAudioFrame（含 uid）
joinConfig.subscribeAudioFormat = AliRTCLinuxEngine.AudioFormat.AudioFormatMixedPcm;

// 接收 H264 视频帧，触发 onRemoteVideoSample
joinConfig.subscribeVideoFormat = AliRTCLinuxEngine.VideoFormat.VideoFormatH264;

步骤七：加入频道

调用 joinChannel 传入步骤三生成的 Token 和频道配置加入频道。

// 调用 joinChannel 加入频道
engineIns.joinChannel(authInfo, joinConfig);

步骤八：推送外部视频帧

Linux 平台没有内置摄像头驱动接口，通过外部输入将 YUV 视频数据送入 SDK。以下示例从 I420 格式 YUV 文件循环读取帧数据推送，实际业务中可替换为摄像头驱动或视频解码器输出。

Thread videoThread = new Thread(() -> {
    int width     = 720;
    int height    = 1280;
    int fps       = 15;
    int frameSize = width * height * 3 / 2; // I420

    try (FileInputStream fis = new FileInputStream("/tmp/test_720p.yuv")) {

        byte[ ] buf = new byte[frameSize];

        AliRTCLinuxEngine.VideoDataSample sample = new AliRTCLinuxEngine.VideoDataSample();

        while (running && !Thread.currentThread().isInterrupted()) {
            int readSize = fis.read(buf, 0, frameSize);
            if (readSize != frameSize) {
                fis.getChannel().position(0); // 文件读完后循环重读
                continue;
            }

            sample.data       = buf;
            sample.format     = AliRTCLinuxEngine.VideoDataFormat.VideoDataFormatI420;
            sample.bufferType = AliRTCLinuxEngine.VideoBufferType.VideoBufferTypeRawData;
            sample.width      = width;
            sample.height     = height;
            sample.strideY    = width;
            sample.strideU    = width / 2;
            sample.strideV    = width / 2;
            sample.dataLen    = frameSize;
            sample.rotation   = 0;
            sample.timeStamp  = System.currentTimeMillis();

            int ret = engineIns.pushExternalVideoFrame(sample,
                    AliRTCLinuxEngine.VideoSource.VideoSourceCamera);
            if (ret < 0) break;

            Thread.sleep(1000 / fps);
        }
    } catch (IOException | InterruptedException e) {
        Thread.currentThread().interrupt();
    }
});
videoThread.start();

步骤九：推送外部音频帧

Linux 平台没有内置麦克风录音接口，通过外部输入将 PCM 音频数据送入 SDK。以下示例从 PCM 文件（int16_t，16kHz，单声道）循环读取帧数据推送，实际业务中可替换为麦克风驱动或音频解码器输出。

Thread audioThread = new Thread(() -> {
    int sampleRate = 16000;
    int channels   = 1;
    int frameMs    = 20;  // 每帧 20ms
    int frameSize  = (sampleRate / 1000) * frameMs * 2 * channels; // int16_t = 2 bytes

    try (FileInputStream fis = new FileInputStream("/tmp/test_16k_mono.pcm")) {

        byte[ ] buf = new byte[frameSize];


        while (running && !Thread.currentThread().isInterrupted()) {
            int readSize = fis.read(buf, 0, frameSize);
            if (readSize != frameSize) {
                fis.getChannel().position(0); // 文件读完后循环重读
                continue;
            }

            int ret = engineIns.pushExternalAudioFrameRawData(buf, frameSize, 0);
            if (ret != 0) {
                // SDK buffer 已满，回退文件指针并稍后重试
                fis.getChannel().position(fis.getChannel().position() - readSize);
                Thread.sleep(20);
                continue;
            }

            Thread.sleep(frameMs);
        }
    } catch (IOException | InterruptedException e) {
        Thread.currentThread().interrupt();
    }
});
audioThread.start();

步骤十：处理远端音视频播放

Linux 平台没有内置音视频播放设备，远端音视频数据通过回调帧的方式交给应用层自行处理，例如写入文件、送入解码器或对接播放设备。

音频播放

根据步骤六中 subscribeAudioFormat 的配置，收到远端音频帧时会触发以下回调之一：

// AudioFormatMixedPcm 模式：接收所有远端用户混音后的整频道 PCM 数据
@Override
public void onSubscribeMixedAudioFrame(AliRTCLinuxEngine.AudioFrame frame) {
    if (frame != null && frame.type == AliRTCLinuxEngine.AudioFrameType.AudioFrameRawPcm) {
        AliRTCLinuxEngine.AudioPcmFrame pcmFrame = frame.pcm;

        // pcmFrame.data        PCM 数据（byte[ ]，int16_t 格式）

        // pcmFrame.channels    声道数
        // pcmFrame.sampleRates 采样率
        // 在此写入文件、送入音频设备或解码播放
    }
}

// AudioFormatPcmBeforeMixing 模式：按用户接收未混音的逐路 PCM 数据
@Override
public void onSubscribeAudioFrame(String uid, AliRTCLinuxEngine.AudioFrame frame) {
    if (frame != null && frame.type == AliRTCLinuxEngine.AudioFrameType.AudioFrameRawPcm) {
        // uid 标识该帧来自哪个远端用户
        // 在此按用户分别处理音频数据
    }
}

视频播放

收到远端视频帧时触发 onRemoteVideoSample 回调，帧格式由步骤六中 subscribeVideoFormat 决定：

@Override
public void onRemoteVideoSample(String uid, AliRTCLinuxEngine.VideoFrame frame) {
    if (frame != null && frame.type == AliRTCLinuxEngine.VideoFrameType.VideoFrameH264) {
        AliRTCLinuxEngine.VideoH264Frame h264Frame = frame.h264;
        // uid 标识该帧来自哪个远端用户
        // 在此写入文件、送入渲染器或视频解码器
    }
}

步骤十一：离开频道并销毁引擎

正确释放资源，依次停止推流、离会、销毁引擎。

// 停止外部推流线程
running = false;
videoThread.interrupt();
audioThread.interrupt();
videoThread.join(1000);
audioThread.join(1000);

// 调用 publishLocalVideoStream(false) / publishLocalAudioStream(false) 停止发布
engineIns.publishLocalVideoStream(false);
engineIns.publishLocalAudioStream(false);

// 调用 leaveChannel 离开频道
engineIns.leaveChannel();

// 等待 onLeaveChannelResult 回调后再销毁引擎
// 调用 release 销毁引擎（须在 leaveChannel 之后调用）
engineIns.release();
engineIns = null;