This topic describes the auto chapters feature, including its AI capabilities and implementation. This feature segments audio and video content by topic and then generates a title and summary for each segment. You can use auto chapters to quickly understand the structure of your content or find specific topics within long content.
Request parameters
Parameter | Type | Required | Description |
AutoChaptersEnabled | boolean | No | The default value is false. |
AutoChapters | Object | No | The control parameter object for auto chapters. |
AutoChapters.ChapterGranularity | String | No | The chapter granularity. Valid values: Coarse, General, and Meticulous. If you do not specify this parameter, the default value Meticulous is used. Coarse: Generates about 4 chapters per hour of audio or video. General: Generates about 6 chapters per hour of audio or video. Meticulous: Generates about 12 to 15 chapters per hour of audio or video. |
AutoChapters.TitleLengthLevel | String | No | The length of chapter titles. Valid values: Short, Normal, and Long. If you do not specify this parameter, the default value Long is used. Short: 6 to 25 characters, with an average of about 13 characters. Normal: 10 to 28 characters, with an average of about 16 characters. Long: 10 to 30 characters, with an average of about 20 characters. |
For descriptions of other request parameters, see the document for your scenario:
Example settings
{
"Input":{
...
},
"Parameters":{
...
"AutoChaptersEnabled": true,
"AutoChapters": {
"ChapterGranularity": "Coarse",
"TitleLengthLevel": "Short"
}
...
}
}Code examples
#!/usr/bin/env python
#coding=utf-8
import os
import json
import datetime
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest
from aliyunsdkcore.auth.credentials import AccessKeyCredential
def create_common_request(domain, version, protocolType, method, uri):
request = CommonRequest()
request.set_accept_format('json')
request.set_domain(domain)
request.set_version(version)
request.set_protocol_type(protocolType)
request.set_method(method)
request.set_uri_pattern(uri)
request.add_header('Content-Type', 'application/json')
return request
def init_parameters():
root = dict()
root['AppKey'] = 'Enter the AppKey that you created in the Tingwu console'
# Basic request parameters
input = dict()
input['SourceLanguage'] = 'cn'
input['TaskKey'] = 'task' + datetime.datetime.now().strftime('%Y%m%d%H%M%S')
input['FileUrl'] = 'Enter the URL of the audio file to test'
root['Input'] = input
# AI-related parameters. Set them as needed.
parameters = dict()
# Auto chapters
parameters['AutoChaptersEnabled'] = True
parameters['AutoChapters'] = {
"ChapterGranularity": "Coarse",
"TitleLengthLevel": "Short"
}
root['Parameters'] = parameters
return root
body = init_parameters()
print(body)
# TODO: Set your AccessKeyId and AccessKeySecret as environment variables.
credentials = AccessKeyCredential(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'])
client = AcsClient(region_id='cn-beijing', credential=credentials)
request = create_common_request('tingwu.cn-beijing.aliyuncs.com', '2023-09-30', 'https', 'PUT', '/openapi/tingwu/v2/tasks')
request.add_query_param('type', 'offline')
request.set_content(json.dumps(body).encode('utf-8'))
response = client.do_action_with_exception(request)
print("response: \n" + json.dumps(json.loads(response), indent=4, ensure_ascii=False))package com.alibaba.tingwu.client.demo.aitest;
import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;
import org.junit.Test;
/**
* @author tingwu2023
*/
public class AutoChaptersTest {
@Test
public void testAutoChapters() throws ClientException {
CommonRequest request = createCommonRequest("tingwu.cn-beijing.aliyuncs.com", "2023-09-30", ProtocolType.HTTPS, MethodType.PUT, "/openapi/tingwu/v2/tasks");
request.putQueryParameter("type", "offline");
JSONObject root = new JSONObject();
root.put("AppKey", "Enter the AppKey that you created in the Tingwu console");
JSONObject input = new JSONObject();
input.fluentPut("FileUrl", "Enter the URL of the audio file to test")
.fluentPut("SourceLanguage", "cn")
.fluentPut("TaskKey", "task" + System.currentTimeMillis());
root.put("Input", input);
JSONObject parameters = new JSONObject();
parameters.put("AutoChaptersEnabled", true);
JSONObject autoChapters = new JSONObject();
autoChapters.put("ChapterGranularity", "Coarse");
autoChapters.put("TitleLengthLevel", "Short");
parameters.put("AutoChapters", autoChapters);
root.put("Parameters", parameters);
System.out.println(root.toJSONString());
request.setHttpContent(root.toJSONString().getBytes(), "utf-8", FormatType.JSON);
// TODO: Set your AccessKeyId and AccessKeySecret as environment variables.
DefaultProfile profile = DefaultProfile.getProfile("cn-beijing", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
IAcsClient client = new DefaultAcsClient(profile);
CommonResponse response = client.getCommonResponse(request);
System.out.println(response.getData());
}
public static CommonRequest createCommonRequest(String domain, String version, ProtocolType protocolType, MethodType method, String uri) {
// Create an API request and set its parameters.
CommonRequest request = new CommonRequest();
request.setSysDomain(domain);
request.setSysVersion(version);
request.setSysProtocol(protocolType);
request.setSysMethod(method);
request.setSysUriPattern(uri);
request.setHttpContentType(FormatType.JSON);
return request;
}
}Example output
{
"Message": "success",
"Code": "0",
"Data": {
"Result": {
"Transcription": "http://speech-swap-hangzhou.oss-cn-hangzhou.aliyuncs.com/tingwu/output/1503864348104017/05c45066fc6d496dae9b583426fdaae8/05c45066fc6d496dae9b583426fdaae8_Transcription_20231028230430.json?Expires=1698593389&OSSAccessKeyId=LTAI****************&Signature=*********huzKcM4tzimubU%3D",
"AutoChapters": "http://speech-swap-hangzhou.oss-cn-hangzhou.aliyuncs.com/tingwu/output/1503864348104017/05c45066fc6d496dae9b583426fdaae8/05c45066fc6d496dae9b583426fdaae8_AutoChapters_20231028230459.json?Expires=1698593389&OSSAccessKeyId=LTAI****************&Signature=*********V8O%2BG4paM0VMv0AIyK4%3D"
},
"TaskId": "05c45066fc6df96dg09bf8z4*********",
"TaskStatus": "COMPLETED"
},
"RequestId": "7AE5CB5C-7287-16D1-BA93-G43********"
}The value of the AutoChapters field is the HTTP URL from which you can download the auto chapters results.
Protocol parsing
The content at the URL for the auto chapters results is a JSON message. The following example shows the message format.
{
"TaskId":"05c45066fc6df96dg09bf8z4*********",
"AutoChapters":[
{
"Id":1,
"Start":1930,
"End":283874,
"Headline":"Alibaba Cloud Apsara Conference and technical responsibility",
"Summary":"The Apsara Conference is a major event for China's industry and a forum for discussions in the digital era. Alibaba Cloud supports young scientists in their pursuit of scientific advancement through the DAMO Academy Young Fellow award. Alibaba Cloud continues to develop its cloud computing and digital ecosystem, striving to become a world-leading computing infrastructure. Alibaba also pursues technological advancement, including a self-developed cloud operating system and the training of algorithmic models. Alibaba hopes to enable everyone to benefit from and create with data through a low-code environment. In the chip realm, Alibaba is also working to make breakthroughs in core technologies."
},
{
"Id":2,
"Start":284050,
"End":452084,
"Headline":"Cloud computing: Driving China's modernization",
"Summary":"T-Head defined the YiTian 710 processor for cloud computing scenarios and helped host the Winter Olympics on the cloud. Cloud computing introduces new production and management methods across all industries, driving China's modernization. Alibaba is committed to technological advancement and takes on greater responsibility for social development, striving to make cloud computing a green engine for sustainable growth."
}
]
}The fields are described as follows.
Parameter | Type | Description |
TaskId | string | The ID of the task. |
AutoChapters | list[] | A collection of auto chapter information. It can contain zero, one, or multiple chapters. |
AutoChapters[i].Id | int | The ordinal number of the chapter. |
AutoChapters[i].Start | long | The start time of the chapter relative to the beginning of the audio. This is a relative timestamp in milliseconds. |
AutoChapters[i].End | long | The end time of the chapter relative to the beginning of the audio. This is a relative timestamp in milliseconds. |
AutoChapters[i].Headline | string | A one-sentence title for the chapter. |
AutoChapters[i].Summary | string | The summary of the chapter. |
FAQ
When can I call the auto chapters feature?
You can enable this feature when you create an offline transcription task for an audio or video file, or when you create a real-time meeting.
You can also rerun a task after an offline transcription or real-time meeting ends to generate chapter information. You must use the same TaskId for the rerun request.
Why are no auto chapters generated, or why is the result empty after I call the feature?
The call parameters may not be enabled or may be set incorrectly. Check the developer documentation and ensure that the parameters are configured correctly.
The selected language model may not support chapter generation. For example, the auto chapters feature is not currently supported for Japanese audio or video files.
The audio or video file may not contain enough information. For example, if the Automatic Speech Recognition (ASR) result contains insufficient information due to excessive background noise or poor audio quality, the model cannot generate chapters. In this case, try using a different audio or video file with more relevant content.