Record

loopingrage edited this page Dec 1, 2011 · 1 revision

The Record API lets you store your calls and conferences and also offers you tons of options to configure how the recording will be done. These is how it works:

You can send an empty record request. Rayo will start recording your call and will give you a link to the file. By default, Rayo will create an mp3 file and store it in the filesystem returning an URI to it. However, an Rayo server should let you plug your own storage strategies so you could do things like for example storing conversations in Amazon S3. This is the simplest way to do a record:

<iq type='set' to='9f00061@call.rayo.net/1' from='16577@app.rayo.net/1'>
  <record xmlns='urn:xmpp:rayo:record:1'/> 
</iq>

There is multiple optional attributes that you can use to configure how the recording will be done. Here you have an example with all the available attributes:

<iq type='set' to='9f00061@call.rayo.net/1' from='16577@app.rayo.net/1'>
  <record xmlns='urn:xmpp:rayo:record:1' 
      format='mp3'
      start-beep='true'
      start-paused='false'
      max-duration='500000'
      initial-timeout='10000|none'
      final-timeout='30000|none'>
      <!-- Optional format-specific encoding hints -->
      <hint name="quality" value="4" />
      <hint name="double-pass" value="true" />
  </record>
</iq>

Below you will find the description for all possible attributes.

  • format: File format used during recording.
  • start-beep: Indicates whether subsequent record will be preceded with a beep. Default is true.
  • start-paused: Whether subsequent record will start in PAUSE mode. Default is false.
  • max-duration: Indicates the maximum duration (milliseconds) for a recording.
  • initial-timeout: Controls how long (milliseconds) the recognizer should wait after the end of the prompt for the caller to speak before sending a Recorder event.
  • final-timeout: Controls the length (milliseconds) of a period of silence after callers have spoken to conclude they finished.

Commands

  <!-- Client pause the record -->
  <iq type='set' to='9f00061@call.rayo.net/fgh4590' from='16577@app.rayo.net/1'>
    <pause xmlns='urn:xmpp:rayo:record:1' />    
  </iq>

  <!-- Client resumes the record -->
  <iq type='set' to='9f00061@call.rayo.net/fgh4590' from='16577@app.rayo.net/1'>
    <resume xmlns='urn:xmpp:rayo:record:1' />    
  </iq>

  <!-- Client stops the record -->
  <iq type='set' to='9f00061@call.rayo.net/fgh4590' from='16577@app.rayo.net/1'>
    <stop xmlns='urn:xmpp:rayo:ext:1'/>    
  </iq>

Events

The Record complete event signals the end of the recording. There is three attributes on each recording element:

  • uri: URI of the resulting file
  • duration: Length of the recording in milliseconds
  • size: Size of the recording in bytes
  <!-- Recording completed successfully -->
  <presence to='16577@app.rayo.net/1' from='9f00061@call.rayo.net/fgh4590'>
    <complete xmlns='urn:xmpp:rayo:ext:1'>
      <success xmlns='urn:xmpp:rayo:record:complete:1'/>
      <recording xmlns='urn:xmpp:rayo:record:complete:1' 
           uri="file:/tmp/rayo7451601434771683422.mp3"
           duration="34000"
           size="23450"/>
    </complete>
  </presence>

  <!-- Recording was stopped -->
  <presence to='16577@app.rayo.net/1' from='9f00061@call.rayo.net/fgh4590'>
    <complete xmlns='urn:xmpp:rayo:ext:1'>
      <stop xmlns='urn:xmpp:rayo:ext:complete:1' />
      <recording xmlns='urn:xmpp:rayo:record:complete:1' 
           uri="file:/tmp/rayo7451601434771683422.mp3"
           duration="34000"
           size="23450"/>
    </complete>
  </presence>

  <!-- Component completed because the record was disconnected -->
  <presence to='16577@app.rayo.net/1' from='9f00061@call.rayo.net/fgh4590'>
    <complete xmlns='urn:xmpp:rayo:ext:1'>
      <hangup xmlns='urn:xmpp:rayo:ext:complete:1' />
      <recording xmlns='urn:xmpp:rayo:record:complete:1' 
           uri="file:/tmp/rayo7451601434771683422.mp3"
           duration="34000"
           size="23450"/>
    </complete>
  </presence>

  <!-- Component completed because the record timed out or there was some error -->
  <presence to='16577@app.rayo.net/1' from='9f00061@call.rayo.net/fgh4590'>
    <complete xmlns='urn:xmpp:rayo:ext:1'>
      <error xmlns='urn:xmpp:rayo:ext:complete:1'>
        Something really bad happened
      </error>
    </complete>
  </presence>