Kakao i Agent::AI Service Agent::Player Queue

페이지 이동경로

Player Queue

오디오 재생을 수행하는 AudioPlayer 인터페이스는 음성을 통해 오디오 재생을 제어하는 Instruction과 재생 진행을 관리하고 모니터링하는 Event로 구성됩니다. 음성을 통해 오디오 재생 기능을 사용하기 위해서는 사전에 Service Agent에 Player Queue(내장 Audio Player)를 구현해야 합니다. 음성 답변은 콘텐츠 타입에 따라 Play 채널, Speak 채널, Alert 채널, 시보 채널로 분류되어 재생됩니다.

안내
각 채널별로 다른 동작 규칙이 적용됩니다.

Play 채널

Play 채널은 음성 재생 시간이 긴 음악, 라디오 및 팟캐스트 등을 Content Audio Player에서 재생합니다. Play 채널의 콘텐츠는 음성형음악형으로 구분되며, 콘텐츠 유형에 따라 동작이 달라집니다.

Play 채널 콘텐츠
구분 설명
음성형 뉴스, 팟캐스트 유형의 콘텐츠
- 다른 채널을 재생할 경우에는 일시 정지 상태로 변경됨
음악형 음악, 라디오 유형의 콘텐츠
- 다른 채널을 재생할 경우에는 최소 볼륨으로 재생됨

음성형인 경우

Play 채널의 음성형 콘텐츠는 Behavior(Action) 타입에 따라 다르게 동작하며, 타입별로 재생 목록의 순서에 영향을 줍니다. 일반적으로 REPLACE_ALL로 동작하며, 사용자 명령어에 따라 다른 동작 타입이 설정될 수 있습니다.

Play 채널의 Behavior(Action)
타입 설명 명령어 예시
REPLACE_ALL 기존 재생 응답은 중지하고, 새 재생 응답을 재생 멜론 탑백 틀어줘
ENQUEUE 기존 재생 목록에 현재 재생 중인 응답 다음으로 새 재생 응답을 추가 이 노래 다음에 아이유의 좋은날 틀어줘
REPLACE_ENQUEUED 현재 재생 중인 응답 다음으로 새 재생 목록 재생 이 노래 다음에 멜론 탑백 틀어줘

Play 채널 적용 규칙

  • Play 채널은 일반적으로 ContentState의 상태 값으로 설정되어 재생됩니다.
  • 하지만, 일부 음성의 경우 다른 동작을 하기 위해 PlayState를 참조할 수 있습니다.
Play 채널 상태값
상태값 설명 예시
ContentState 재생 컨트롤이 필요한 응답의 상태 뉴스, 음악, 팟캐스트 등
PlayState Play 채널로 재생하지만 Speak 채널의 동작을 적용하기 위한 상태 운세, 어학사전 등

음성형 재생 예시

코드예제AudioPlayer.Play Instruction 중 일부

{
   "instruction":{
      "body":{
         "action":"REPLACE_ALL",
         "audioItem":{
            "url":"https://.../",
            "format":"AUDIO_MPEG",
            "source":"podcast",
            "duration":2968000,
            "audioType":"speak",
            "contentMeta":{
               "image":"http://sample_img_url/image_id/.../",
               "subtitle":"팟캐스트 부 제목",
               "title":"팟캐스트 타이틀"
            }
         },
         "playChannel":"content",
         "controllable":[
            ...
         ]
      }
   }
}

Speak 채널

Speak 채널은 시간, 날씨 안내 등의 짧은 응답을 재생합니다.

Speak 채널 적용 규칙

  • Speak 채널은 응답을 재생하는 도중에는 다른 채널의 응답을 재생하지 않습니다.
  • 만약 응답이 중단되더라도, 재생이 중단된 응답을 다시 재생하지 않습니다.

오늘의 날씨 응답 예시

코드예제Synthesizer.Speak Instruction 중 일부

{
   "instruction":{
      "header":{
         "type":"Synthesizer.Speak",
         "messageId":"...",
         "dialogRequestId":"..."
      },
      "body":{
         "url":"...",
         "format":"AUDIO_MPEG",
         "token":"...",
         "mood":"neutral",
         "action":"REPLACE_ALL",
         "text":"현재 삼평동은 맑아. 이후에도 맑겠어."
      }
   }
}

Alert 채널

Alert 채널은 타이머, 알람처럼 시간에 맞춰서 재생해야 하는 콘텐츠를 재생합니다.

Alert 채널 적용 규칙

  • 만약 알람 소리를 재생하는 중 발화(음성 또는 버튼 웨이크업)를 활성화하면 알람은 종료됩니다.
  • 알람은 최대 60분까지 재생되며, 이후에는 자동으로 종료됩니다.
  • 알람 소리 재생 중 새 알람이 활성화되면, 기존 알람은 종료되고 새 알람이 실행됩니다.
  • 알람은 최대 50개까지 설정 가능합니다.
  • 알람에 사용되는 벨소리는 전체 알람에 공통으로 1곡이 적용되며, 음악으로 설정할 수 있습니다.
  • 타이머는 1개만 설정 가능하며, 벨소리는 음악으로 설정할 수 없습니다.
  • 볼륨 10단계를 기준으로, 볼륨이 6 미만일 때는 15초마다 1단계씩 볼륨 레벨이 최대 6단계까지 증가합니다.

시보 채널

시보 채널은 다른 채널과 상호작용 없이 정시 정각에 시간을 알려주는 알람음을 재생합니다.

시보 채널 적용 규칙

  • 알람 소리는 뻐꾸기 울음소리로 고정됩니다.
  • 알람을 실행할 시간 범위는 사용자가 설정할 수 있습니다.

시보 설정 시나리오

  1. 사용자가 “헤이 카카오! 뻐꾸기 설정해줘!”라고 발화합니다.(Recognizer.Speech)
  2. Service Agent가 “매일 오전 10시부터 오후 8시까지 정각에 시간 알려줄게요”라는 응답을 출력합니다.(Synthesizer.Speak)
  3. 설정값 동기화(설정 시간)가 진행됩니다. (System.RequestSynchronizeState)
  4. 설정된 시간에 맞춰 로컬 타이머가 등록되며, 정각마다 알람이 실행됩니다.

시보 설정 예시

코드예제System.RequestSynchronizeState Instruction 중 일부

{
   "instruction":{
      "header":{
         "type":"System.RequestSynchronizeState",
         "messageId":"...",
         "dialogRequestId":"..."
         },
      "body":{
         "settings":[
            {
               "key":"timeSignalSetTimes",
               "value":"10:00,11:00,12:00,13:00,14:00,15:00,16:00,17:00,18:00,19:00,20:00"
            },
            {
               "key":"timeSignalSoundType",
               "value":"default"
            }
         ]
      }
   }
}

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.