SR

노래 신청(SR)의 재생 상태와 대기열을 조회하고 재생을 제어합니다. 조회와 제어 모두 sr:control 권한을 씁니다.

SR 상태 조회

재생 상태, SR 설정, 신청 리스트와 스트리머 리스트 대기열을 한 번에 돌려줍니다. 대시보드와 방송 화면 플레이어가 받는 상태와 같은 형식입니다.

요청

요청 파라미터가 없습니다.

GET /api/v1/developer/sr
Authorization: Bearer ACCESS_TOKEN

응답

settings.status 값입니다.

재생·일시정지 중인 곡은 끝나거나 건너뛸 때까지 대기열에 남아 있습니다. settings.current_video_type 목록에서 video_id가 settings.current_video_id와 같은 첫 항목이 지금 곡입니다.

{
  "type": "state",
  "settings": {
    "status": "play_user",
    "is_accepting": true,
    "max_request_per_user": 5,
    "max_request_per_subscriber": null,
    "max_request_per_follower": null,
    "max_duration": 600,
    "require_point": 0,
    "no_duplicate": false,
    "volume": 80,
    "captions_enabled": false,
    "auto_advance": true,
    "block_shorts": false,
    "current_video_id": "a1B2c3D4e5F",
    "current_video_type": "user",
    "current_video_title": "아이유 - 밤편지"
  },
  "lists": {
    "user": [
      {
        "id": 1532,
        "list_type": "user",
        "user_uid": "fedcba9876543210fedcba9876543210",
        "video_id": "a1B2c3D4e5F",
        "video_name": "아이유 - 밤편지",
        "video_duration": 254,
        "order_index": 0,
        "created_at": "2026-10-05T21:02:11.204000",
        "user_nickname": "시청자닉네임"
      }
    ],
    "streamer": []
  }
}

오류

재생 제어

재생, 일시정지, 정지, 다음 곡, 처음부터 다시 재생을 지시합니다. 바뀐 상태는 대시보드와 방송 화면 플레이어에 바로 반영되고 응답으로도 돌아옵니다.

요청

다음 곡은 신청 리스트 맨 위 곡이고, 신청 리스트가 비었으면 스트리머 리스트 맨 위 곡입니다. 두 목록이 모두 비었으면 waiting 상태가 되고, 그 뒤 들어오는 신청은 바로 재생됩니다. 빈 대기열에서 play·skip·restart 를 보내도 waiting 입니다. play의 이어서 재생과 restart의 처음부터 재생이 대시보드 버튼·채팅 명령과 어떻게 대응하는지는 재생 조작하기와 채팅으로 조작하기를 참고하세요.

POST /api/v1/developer/sr/control
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{"action": "pause"}

응답

{
  "ok": true,
  "state": {
    "type": "state",
    "settings": {
      "status": "pause_user",
      "is_accepting": true,
      "max_request_per_user": 5,
      "max_request_per_subscriber": null,
      "max_request_per_follower": null,
      "max_duration": 600,
      "require_point": 0,
      "no_duplicate": false,
      "volume": 80,
      "captions_enabled": false,
      "auto_advance": true,
      "block_shorts": false,
      "current_video_id": "a1B2c3D4e5F",
      "current_video_type": "user",
      "current_video_title": "아이유 - 밤편지"
    },
    "lists": {
      "user": [
        {
          "id": 1532,
          "list_type": "user",
          "user_uid": "fedcba9876543210fedcba9876543210",
          "video_id": "a1B2c3D4e5F",
          "video_name": "아이유 - 밤편지",
          "video_duration": 254,
          "order_index": 0,
          "created_at": "2026-10-05T21:02:11.204000",
          "user_nickname": "시청자닉네임"
        }
      ],
      "streamer": []
    }
  }
}

오류

{"detail": "action 은 play|pause|stop|skip|restart 중 하나"}