Time Analysis

This guide demonstrates how to run Time Analysis with Phonexia Speech Platform 4 Virtual Appliance. The technology extracts basic information from dialogue in a stereo media file, providing essential knowledge about the conversation flow. You can find a high-level description in the Time Analysis of Speech article.

For testing, we'll be using the following stereo-channel media file Jennifer_Pavla.wav with the conversation between a customer and an operator. We want to analyze this conversation and get information about the average reaction time of the operator speaking in first channel.

At the end of this guide, you'll find the full Python code example that combines all the steps that will first be discussed separately. This guide should give you a comprehensive understanding on how to integrate Time Analysis in your own projects.

Prerequisites

Follow the prerequisites for setup of Virtual Appliance and Python environment as described in the Task lifecycle code examples.

Run Time Analysis

To run Time Analysis for a single media file, you should start by sending a POST request to the /api/technology/time-analysis endpoint. In most cases, file is the only mandatory parameter, however, the technology can only process up to 2 channels, so for media files with more channels, you must use the channels query parameter to specify which ones to use.

In Python, a simple request without query parameters can be created as follows:

import requests

VIRTUAL_APPLIANCE_ADDRESS = "http://<virtual-appliance-address>:8000"  # Replace with your address
MEDIA_FILE_BASED_ENDPOINT_URL = f"{VIRTUAL_APPLIANCE_ADDRESS}/api/technology/time-analysis"

media_file = "Jennifer_Pavla.wav"

with open(media_file, mode="rb") as file:
    files = {"file": file}
    start_task_response = requests.post(
        url=MEDIA_FILE_BASED_ENDPOINT_URL,
        files=files,
    )
print(start_task_response.status_code)  # Should print '202'

If the task was successfully accepted, 202 code will be returned together with a unique task ID in the response body. The task isn't immediately processed, but only scheduled for processing. You can check the current task status whilst polling for the result.

Polling

To obtain the final result, periodically query the task status until the task state changes to done, failed or rejected. The general polling procedure is described in detail in the Task lifecycle code examples.

Result for Time Analysis

The result field of the task contains the channel_analyses and--when two channels from the input media have been processed--the reaction_analyses. The channel_analyses list contains information about individual channels. And the reaction_analyses describe reactions between the two channels.

For our sample file, the task result should look as follows:

{
  "task": {
    "task_id": "602a9699-bfdc-47fe-b829-d44bec317a4a",
    "state": "done"
  },
  "result": {
    "channel_analyses": [
      {
        "channel_number": 0,
        "speech_duration": 43.09,
        "speech_rate": 8.586679458618164,
        "total_duration": 119.29
      },
      {
        "channel_number": 1,
        "speech_duration": 68.65,
        "speech_rate": 9.919883728027344,
        "total_duration": 120.314999999
      }
    ],
    "reaction_analyses": [
      {
        "reacting_channel": 1,
        "reactions_count": 7,
        "average_reaction_time": 0.49499997,
        "slowest_reaction_position": {
          "start_time": 96.025,
          "end_time": 96.159999999
        },
        "fastest_reaction_position": {
          "start_time": 71.189999999,
          "end_time": 72.215
        },
        "crosstalks": []
      },
      {
        "reacting_channel": 0,
        "reactions_count": 8,
        "average_reaction_time": 0.36125,
        "slowest_reaction_position": {
          "start_time": 70.23,
          "end_time": 70.269999999
        },
        "fastest_reaction_position": {
          "start_time": 14.005,
          "end_time": 14.929999999
        },
        "crosstalks": []
      }
    ]
  }
}

Full Python Code

Here is the full example on how to run the Time Analysis technology. The code is slightly adjusted and wrapped into functions for better readability. Refer to the Task lifecycle code examples for a generic code template, applicable to all technologies.

import json
import requests
import time

VIRTUAL_APPLIANCE_ADDRESS = "http://<virtual-appliance-address>:8000"  # Replace with your address

MEDIA_FILE_BASED_ENDPOINT_URL = f"{VIRTUAL_APPLIANCE_ADDRESS}/api/technology/time-analysis"


def poll_result(polling_url, polling_interval=5):
    """Poll the task endpoint until processing completes."""
    while True:
        polling_task_response = requests.get(polling_url)
        polling_task_response.raise_for_status()
        polling_task_response_json = polling_task_response.json()
        task_state = polling_task_response_json["task"]["state"]
        if task_state in {"done", "failed", "rejected"}:
            break
        time.sleep(polling_interval)
    return polling_task_response


def run_media_based_task(media_file, params=None, config=None):
    """Create a media-based task and wait for results."""
    if params is None:
        params = {}
    if config is None:
        config = {}

    with open(media_file, mode="rb") as file:
        files = {"file": file}
        start_task_response = requests.post(
            url=MEDIA_FILE_BASED_ENDPOINT_URL,
            files=files,
            params=params,
            data={"config": json.dumps(config)},
        )
        start_task_response.raise_for_status()
    polling_url = start_task_response.headers["Location"]
    task_result = poll_result(polling_url)
    return task_result.json()


# Run Time Analysis
media_file = "Jennifer_Pavla.wav"

media_file_based_task_result = run_media_based_task(media_file)
print(f"Time Analysis:\n{json.dumps(media_file_based_task_result["result"], indent=2)}")