agora-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4086d655e80b6377412e1830af2f16b3b7f4fc2f5cc746c9e50a1cc56cee72dc
+  data.tar.gz: c28cf48f91c5e343b03c3ce1eaedb92bdc8774bae19a68b82a6cde0c9aaa52ce
+SHA512:
+  metadata.gz: 7a8ffc3b500fae010a7971a30a59be3aa3cbcce48bc735adbb92f8c3c1d488b0add121e10640a1995c7bf561a94caadd84b1e03c2a4be9a023e3449e1c1348ad
+  data.tar.gz: c36b354a9f070c5c09b8f9425260c9a28bcbc97d6db08063a29e3e779300a64eb3c3e93d1238e486da412794c152cefbf58ba00b2402371d3feb5d38724739e6

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.4
+before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in agora-ruby.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+
+group :test do
+  gem "webmock", "~> 3.0"
+end

data/Gemfile.lock

@@ -0,0 +1,56 @@
+PATH
+  remote: .
+  specs:
+    agora-ruby (0.1.0)
+      httparty (~> 0.20)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    bigdecimal (3.1.9)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    csv (3.3.4)
+    diff-lcs (1.4.4)
+    hashdiff (1.1.2)
+    httparty (0.23.1)
+      csv
+      mini_mime (>= 1.0.0)
+      multi_xml (>= 0.5.2)
+    mini_mime (1.1.5)
+    multi_xml (0.6.0)
+    public_suffix (5.1.1)
+    rake (13.0.6)
+    rexml (3.4.1)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  agora-ruby!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 yfscret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# 声网（Agora）Ruby 客户端
+
+[![Gem Version](https://badge.fury.io/rb/agora-ruby.svg)](https://badge.fury.io/rb/agora-ruby) <!-- 发布后可更新 -->
+
+本 Ruby gem 提供了对接声网 Agora RESTful API 的客户端，当前聚焦于云端录制功能。它简化了录制任务的发起、停止、查询，以及录制文件上传到第三方云存储平台（如阿里云 OSS、Amazon S3 等）的流程。
+
+## 安装
+
+在你的 Gemfile 中添加：
+
+```ruby
+gem 'agora-ruby'
+```
+
+然后执行：
+
+```bash
+$ bundle install
+```
+
+或者直接安装：
+
+```bash
+$ gem install agora-ruby
+```
+
+## 配置
+
+在使用本 gem 前，你需要配置声网和第三方云存储的相关参数。推荐在 Rails 项目中放在 `config/initializers/agora.rb`，普通 Ruby 项目可在初始化阶段配置：
+
+```ruby
+Agora.configure do |config|
+  # 声网相关配置（必填）
+  config.app_id = '你的声网 App ID'
+  config.customer_key = '你的声网 RESTFUL API 客户 ID'
+  config.customer_secret = '你的声网 RESTFUL API 客户密钥'
+
+  # 第三方云存储平台配置（必填，vendor 需根据实际平台填写）
+  # 支持的 vendor 及编号如下：
+  # 1：Amazon S3
+  # 2：阿里云 OSS
+  # 3：腾讯云 COS
+  # 5：Microsoft Azure
+  # 6：谷歌云 GCS
+  # 7：华为云 OBS
+  # 8：百度智能云 BOS
+  config.oss_vendor = 2 # 2 表示阿里云 OSS
+  config.oss_region = 1 # 区域编号，具体见官方文档 https://doc.shengwang.cn/doc/cloud-recording/restful/api/reference
+  config.oss_bucket = '你的云存储 bucket 名称'
+  config.oss_access_key = '你的云存储 Access Key'
+  config.oss_secret_key = '你的云存储 Secret Key'
+  config.oss_filename_prefix = ["directory1","directory2"] # 录制文件在第三方云存储中的存储位置, directory1/directory2/xxx.m3u8
+end
+```
+
+**安全提示：** 强烈建议通过环境变量或 Rails credentials 等安全方式管理密钥，不要将密钥明文写入代码。
+
+## 使用方法
+
+配置完成后，可通过 `Agora::CloudRecording::Client` 管理云端录制。
+
+### 典型场景：直播连线录制
+
+假设你在直播间（频道名：`"live-chat-123"`）与用户连线，需要录制用户的视频、用户音频和你的音频，录制文件自动上传到阿里云 OSS。
+
+```ruby
+# 确保已完成上述配置
+begin
+  client = Agora::CloudRecording::Client.new
+  cname = "live-chat-123"
+  my_uid = "1888"       # 你的 UID
+  recording_bot_uid = "#{my_uid}#{rand(1000)}" # 录制机器人 UID，需唯一
+  record_uid = "110560" # 需要录制的用户 UID
+
+  # 1. 获取录制资源 resourceId
+  # acquire 的 clientRequest 可为空，除非有特殊需求
+  puts "获取录制资源..."
+  acquire_response = client.acquire(cname, recording_bot_uid)
+  resource_id = acquire_response["resourceId"]
+  puts "resourceId: #{resource_id}"
+
+  # 2. 获取 token
+  # 你需要为 recording_bot_uid 生成一个有效的声网 Token（可用你自己的 Token 服务）
+  app_id = 'xxxxxxx'
+  app_certificate = 'xxxxxxxx'
+  token_expiration_in_seconds = 3600 * 24
+  privilege_expiration_in_seconds = 3600 * 24
+  token = Agora::AgoraDynamicKey2::RtcTokenBuilder.build_token_with_uid(
+    app_id, app_certificate, cname, recording_bot_uid,
+    Agora::AgoraDynamicKey2::RtcTokenBuilder::ROLE_PUBLISHER,
+    token_expiration_in_seconds, privilege_expiration_in_seconds
+  )
+
+  # 3. 启动录制
+  recording_config = {
+    streamTypes: 2,  # 录制音视频
+    channelType: 1,  # 直播模式
+    audioProfile: 2, # 音频质量, 音频编码，双声道，编码码率约 192 Kbps。
+    # 只录制指定用户的视频，和你与用户的音频
+    subscribeVideoUids: [record_uid],
+    subscribeAudioUids: [my_uid, record_uid],
+    transcodingConfig: {
+      width: 720,
+      height: 1280,
+      bitrate: 3420,
+      fps: 30
+    }
+  }
+
+  recording_file_config = {
+    avFileType: ["hls", "mp4"] # 同时录制 HLS 和 MP4
+  }
+
+  puts "启动录制..."
+  start_response = client.start(
+    resource_id,
+    cname,
+    recording_bot_uid,
+    token,
+    'mix', # 合流录制，若需单流录制可用 'individual'
+    recording_config,
+    recording_file_config
+  )
+  sid = start_response["sid"] # 录制会话 ID
+  puts "录制已启动，SID: #{sid}"
+
+  # 录制中（实际业务中可根据需求控制时长）
+  puts "录制中..."
+
+  # 4. 可选：查询录制状态
+  puts "查询录制状态..."
+  query_response = client.query(resource_id, sid)
+  puts "状态查询结果: #{query_response}"
+  # 可根据 query_response["serverResponse"]["status"] 判断录制状态
+
+  # 5. 停止录制
+  puts "停止录制..."
+  stop_response = client.stop(resource_id, sid, cname, recording_bot_uid, 'mix', client_request = { async_stop: true })
+  puts "停止结果: #{stop_response}"
+  # 文件上传 OSS 可能有延迟，可通过 stop_response["serverResponse"]["fileList"] 获取文件列表
+
+  puts "录制流程结束，请到 OSS 查看文件: #{Agora.config.oss_bucket}/#{stop_response["serverResponse"]["fileList"][0]['fileName']}"
+
+rescue Agora::Errors::ConfigurationError => e
+  puts "配置错误: #{e.message}"
+rescue Agora::Errors::APIError => e
+  puts "API 错误: #{e.message}"
+  puts "响应码: #{e.response&.code}"
+  puts "响应体: #{e.response&.body}"
+rescue StandardError => e
+  puts "发生未知错误: #{e.message}"
+  puts e.backtrace.join("\n")
+end
+```
+
+### API 方法说明
+
+`Agora::CloudRecording::Client` 提供如下方法：
+
+*   `acquire(cname, uid, client_request = {})`：获取录制资源 resourceId。
+*   `start(resource_id, cname, uid, token, mode = 'mix', recording_config = {}, recording_file_config = {}, storage_config = {})`：启动录制。
+    *   `mode`：'mix'（合流，默认）或 'individual'（单流）。
+    *   `recording_config`：录制参数（如 streamTypes、subscribeVideoUids、subscribeAudioUids、transcodingConfig 等，详见官方文档）。
+    *   `recording_file_config`：输出文件类型（如 avFileType: ["hls", "mp4"]）。
+    *   `storage_config`：云存储参数（如 fileNamePrefix，可覆盖默认值）。
+*   `query(resource_id, sid, mode = 'mix')`：查询录制状态。
+*   `stop(resource_id, sid, cname, uid, mode = 'mix', client_request = {})`：停止录制。
+
+详细参数和更多高级用法请参考 [声网云端录制 RESTful API 文档](https://doc.shengwang.cn/doc/cloud-recording/restful/cloud-recording/overview)。
+
+## 开发与贡献
+
+克隆本仓库后，运行 `bin/setup` 安装依赖。测试可用 `rake spec`（建议补充测试用例）。你也可以用 `bin/console` 进入交互式环境。
+
+本地安装 gem 可用 `bundle exec rake install`。如需发布新版本，修改 `version.rb` 后执行 `bundle exec rake release`，会自动打 tag 并推送到 RubyGems（需先配置好发布信息）。
+
+## 贡献
+
+欢迎通过 Pull Request 或 Issue 反馈和贡献代码，详见 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
+
+## 许可证
+
+本项目基于 [MIT License](https://opensource.org/licenses/MIT) 开源。
+
+## 行为准则
+
+所有参与本项目的人都需遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/agora-ruby.gemspec

@@ -0,0 +1,29 @@
+require_relative 'lib/agora/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "agora-ruby"
+  spec.version       = Agora::VERSION
+  spec.authors       = ["yfscret"]
+  spec.email         = ["yfscret@gmail.com"]
+
+  spec.summary       = %q{A Ruby client for Agora.io RESTful APIs, starting with Cloud Recording.}
+  spec.description   = %q{This gem provides an easy-to-use interface for interacting with Agora.io's RESTful services, initially focusing on cloud recording functionalities, including uploading to Aliyun OSS.}
+  spec.homepage      = "https://rubygems.org/gems/agora-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/yfscret/agora-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/yfscret/agora-ruby"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "httparty", "~> 0.20"
+end

data/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/agora/cloud_recording/client.rb

@@ -0,0 +1,139 @@
+require 'httparty'
+require 'json'
+
+module Agora
+  module CloudRecording
+    class Client
+      include HTTParty
+      # base_uri 通过 Agora.config.base_url 设置
+
+      attr_reader :app_id, :customer_key, :customer_secret, :oss_vendor, :oss_region, :oss_bucket, :oss_access_key, :oss_secret_key, :oss_filename_prefix
+
+      def initialize
+        @config = Agora.config # 使用 Agora.config 获取配置实例
+        unless @config && @config.app_id && @config.customer_key && @config.customer_secret
+          raise Agora::Errors::ConfigurationError, "声网 App ID, Customer ID, 和 Customer Certificate 必须配置。"
+        end
+        unless @config.oss_bucket && @config.oss_access_key && @config.oss_secret_key && @config.oss_region && @config.oss_vendor
+          raise Agora::Errors::ConfigurationError, "云存储的 Bucket, Access Key, Secret Key, Region, 和 Vendor 必须配置。"
+        end
+
+        self.class.base_uri @config.base_url # 设置 base_uri
+
+        @app_id = @config.app_id
+        @customer_key = @config.customer_key
+        @customer_secret = @config.customer_secret
+        @oss_vendor = @config.oss_vendor
+        @oss_region = @config.oss_region
+        @oss_bucket = @config.oss_bucket
+        @oss_access_key = @config.oss_access_key
+        @oss_secret_key = @config.oss_secret_key
+        @oss_filename_prefix = @config.oss_filename_prefix
+      end
+
+      def acquire(cname, uid, client_request = {})
+        path = "/v1/apps/#{@app_id}/cloud_recording/acquire"
+        body = {
+          cname: cname,
+          uid: uid,
+          clientRequest: client_request
+        }.to_json
+
+        headers = {
+          'Authorization' => basic_auth_header,
+          'Content-Type' => 'application/json'
+        }
+        # 注意：HTTParty 的 post/get 方法是类方法
+        handle_response(self.class.post(path, body: body, headers: headers))
+      end
+
+      def start(resource_id, cname, uid, token, mode = 'mix', recording_config = {}, recording_file_config = {}, storage_config = {})
+        path = "/v1/apps/#{@app_id}/cloud_recording/resourceid/#{resource_id}/mode/#{mode}/start"
+
+        default_storage_config = {
+          vendor: @oss_vendor,
+          region: @oss_region,
+          bucket: @oss_bucket,
+          accessKey: @oss_access_key,
+          secretKey: @oss_secret_key,
+          fileNamePrefix: @oss_filename_prefix
+        }
+
+        body = {
+          cname: cname,
+          uid: uid,
+          clientRequest: {
+            token: token,
+            recordingConfig: default_recording_config.merge(recording_config),
+            recordingFileConfig: default_recording_file_config.merge(recording_file_config),
+            storageConfig: default_storage_config.merge(storage_config)
+          }
+        }.to_json
+
+        headers = {
+          'Authorization' => basic_auth_header,
+          'Content-Type' => 'application/json'
+        }
+        handle_response(self.class.post(path, body: body, headers: headers))
+      end
+
+      def query(resource_id, sid, mode = 'mix')
+        path = "/v1/apps/#{@app_id}/cloud_recording/resourceid/#{resource_id}/sid/#{sid}/mode/#{mode}/query"
+        headers = { 'Authorization' => basic_auth_header }
+        handle_response(self.class.get(path, headers: headers))
+      end
+
+      def stop(resource_id, sid, cname, uid, mode = 'mix', client_request = {})
+        path = "/v1/apps/#{@app_id}/cloud_recording/resourceid/#{resource_id}/sid/#{sid}/mode/#{mode}/stop"
+        body = {
+          cname: cname,
+          uid: uid,
+          clientRequest: client_request
+        }.to_json
+
+        headers = {
+          'Authorization' => basic_auth_header,
+          'Content-Type' => 'application/json'
+        }
+        handle_response(self.class.post(path, body: body, headers: headers))
+      end
+
+      private
+
+      def basic_auth_header
+        "Basic " + Base64.strict_encode64("#{@customer_key}:#{@customer_secret}")
+      end
+
+      def handle_response(response)
+        if response.success?
+          response.parsed_response
+        else
+          error_message = "声网 API 错误: #{response.code}"
+          parsed_body = response.parsed_response
+          if parsed_body.is_a?(Hash)
+            reason = parsed_body['reason']
+            message = parsed_body['message']
+            error_message += " - 原因: #{reason}" if reason
+            error_message += " - 信息: #{message}" if message && message != reason # 避免重复信息
+          end
+          raise Agora::Errors::APIError.new(error_message, response)
+        end
+      end
+
+      def default_recording_config
+        {
+          maxIdleTime: 30,
+          streamTypes: 2,
+          channelType: 1,
+        }
+      end
+
+      def default_recording_file_config
+        {
+          avFileType: ["hls", "mp4"]
+        }
+      end
+
+    end
+  end
+end

data/lib/agora/config.rb

@@ -0,0 +1,12 @@
+module Agora
+  class Config
+    attr_accessor :app_id, :customer_key, :customer_secret,
+                  :oss_vendor, :oss_region, :oss_bucket,
+                  :oss_access_key, :oss_secret_key,
+                  :base_url, :oss_filename_prefix
+
+    def initialize
+      @base_url = 'https://api.sd-rtn.com'
+    end
+  end
+end

data/lib/agora/dynamic_key/access_token.rb

@@ -0,0 +1,55 @@
+module Agora::AgoraDynamicKey
+  module Privilege
+    JOIN_CHANNEL = 1
+    PUBLISH_AUDIO_STREAM = 2
+    PUBLISH_VIDEO_STREAM = 3
+    PUBLISH_DATA_STREAM = 4
+    RTM_LOGIN = 1000 # for RTM Only
+  end
+
+  class AccessToken
+    VERSION = "006"
+
+    ONE_DAY = 864_00
+    SEED = 2 ** 32 - 1
+
+    attr_accessor :app_id, :channel_name, :app_certificate,
+                  :uid, :privileges, :privilege_expired_ts,
+                  :salt, :expired_ts
+
+    def initialize args={}
+      @app_id = args[:app_id]
+      @channel_name = args.fetch(:channel_name, "")
+      @app_certificate = args[:app_certificate]
+      @uid = "#{args.fetch(:uid, "")}"
+      @privileges = {}
+      @privilege_expired_ts = args[:privilege_expired_ts]
+      @salt = SecureRandom.rand(SEED)
+      @expired_ts = Time.now.to_i + ONE_DAY
+    end
+
+    def add_privilege privilege, ts
+      privileges[privilege] = ts
+    end
+
+    alias grant add_privilege
+
+    def build
+      Sign.encode self
+    end
+
+    def build!
+      Sign.encode! self
+    end
+
+    def from_string token
+      Sign.decode token
+    end
+
+    def self.generate! payload={}, &block
+      token = AccessToken.new payload
+      block.call token
+      token.build!
+    end
+  end
+end