Alibabacloud Liverecord Diagnosis

Alibaba Cloud Live Recording Diagnostic Skill. Use for diagnosing live stream record issues including missing recordings, file generation problems, unexpected recording behavior, and callback issues. Triggers: "live record", "live stream record diagnosis", "record not working", "record file missing", "record callback issue", "录制诊断", "直播录制问题".

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install alibabacloud-liverecord-diagnosis

Alibaba Cloud Live Recording Diagnostic Skill

Scenario Description

This skill provides comprehensive diagnostic capabilities for Alibaba Cloud ApsaraVideo Live recording issues. It helps identify and troubleshoot problems related to:

Live stream not being recorded
Recording files not generated
Recording files not meeting expectations (missing audio/video, wrong format, etc.)
Recording callbacks not received or incorrect
Other live recording-related issues

Architecture: ApsaraVideo Live + OSS/VOD + Recording Configuration + Callback Configuration

Diagnostic Scope

Within Scope:

Live stream not being recorded
Recording files not generated or incomplete
Recording files missing audio or video tracks
Recording callback issues (not received, incorrect data)
Recording configuration validation
Stream quality issues affecting recording

Out of Scope:

Issues unrelated to live recording (use Alibaba Cloud official AI assistant)
Writing/modifying user configurations (user must modify via console or CLI themselves)

Installation

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low, see references/cli-installation-guide.md for detailed installation instructions.

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

Install Live Plugin:

aliyun plugin install --names live

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

NEVER ask the user to input AK/SK directly in the conversation or command line

NEVER use aliyun configure set with literal credential values

ONLY use aliyun configure list to check credential status
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

Obtain credentials from Alibaba Cloud Console

Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

Return and re-run after aliyun configure list shows a valid profile

RAM Policy

The following RAM permissions are required for this diagnostic skill. See references/ram-policies.md for the complete policy document.

Required Actions:

live:DescribeLiveDomainMapping - Query domain mappings
live:DescribeLiveStreamRecordContent - Query recording content
live:DescribeLiveStreamRecordIndexFiles - Query recording index files
live:DescribeLiveRecordConfig - Query recording configuration
live:DescribeLiveRecordVodConfigs - Query VOD recording configuration
live:DescribeLiveRecordNotifyConfig - Query callback configuration
live:DescribeLiveStreamsOnlineList - Query online streams
live:DescribeLiveStreamsPublishList - Query stream publish history
live:DescribeLiveCenterStreamRateData - Query stream rate data
live:DescribeLiveRecordNotifyRecords - Query callback records

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

Read references/ram-policies.md to get the full list of permissions required by this SKILL

Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., domain names, stream names, application names, time ranges, region IDs, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval. Note that Alibaba Cloud Live API or CLI may UTC timezone. Convert the time from user local zone when calling API/CLI.

Required Parameters:

Parameter Name	Required/Optional	Description	Default Value
`live-stream-url`	Required	The live stream URL to diagnose (used to extract DomainName, AppName, StreamName)	N/A
`issue-description`	Required	Description of the recording issue	N/A
`time-range`	Optional	Time range for diagnosis (format: YYYY-MM-DD HH:mm:ss, user local zone)	Past 1 day (expand to 7 days if no data)
`biz-region-id`	Optional	Business region ID	Default region from CLI config

Core Workflow

At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-liverecord-diagnosis"

Step 1: Identify User Intent and Validate Information Completeness

1.1 Validate Diagnostic Scope

Check if the issue is within the diagnostic scope:

Live stream not recorded
Recording files not generated
Recording files not meeting expectations
Callback issues
Other recording-related problems

If out of scope, politely inform the user to contact Alibaba Cloud support or use the official AI assistant.

1.2 Extract Required Information

From the live stream URL (e.g., rtmp://example.com/live/stream123), extract:

DomainName: The main playback domain (e.g., example.com)
AppName: The application name (e.g., live)
StreamName: The stream name (e.g., stream123)

1.3 Determine Time Range

If user provides time range, use it. Default year is current year if not specified
If not provided, default to past 1 day
If no data found in 1 day, expand to 7 days

1.4 Confirm Parameters with User

Present extracted parameters to user for confirmation:

Diagnostic Parameters:
- Domain: play.example.com
- Application: live
- Stream: stream123
- Time Range: 2026-01-20T00:00:00Z to 2026-01-21T00:00:00Z

Please confirm these parameters are correct before proceeding.

Step 2: Query Domain Mapping and Recording Results

MUST execute steps in this section to verify user's issues.

2.1 Query Domain Mapping

First, query the domain mapping to get the main playback domain:

aliyun live describe-live-domain-mapping \
  --domain-name <DomainName>

See Expected Output for response format. Extract the main playback domain (Type: vhost) for subsequent queries.

2.2 Query Recording Content

MUST execute this step regardless of previous step results. Query recording content for the specified time range.

aliyun live describe-live-stream-record-content \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

See Expected Output for response format.

2.3 Query Recording Index Files (OSS)

If recording to OSS, query index files:

aliyun live describe-live-stream-record-index-files \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

See Expected Output for response format.

2.4 Verify User's Issue

Compare the query results with the user's reported issue:

If recordings exist but user says no recordings → Issue may be with access or playback
If no recordings found → Proceed to Step 3 to check configuration
If recordings exist but incomplete → Check stream quality in Step 5

Step 3: Query Recording Configuration

The recording to VOD/OSS configuration may have wildcard (*) matches for app name, stream name. Use the best matching configuration if there're multiple ones.

3.1 Query Recording to OSS Configuration

aliyun live describe-live-record-config \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName>

See Expected Output for response format.

OnDemand flag in the recording configuration affects whether the record task can be started. Values are as below:

0: auto record
1: call OnDemandUrl in notify configuration to determine if record should be started
7: manual record, user needs to call RealTimeRecordCommand OpenAPI to manual start/stop recording

Validation Checklist:

✅ Configuration exists for the stream
✅ OssBucket and OssEndpoint are correct
✅ RecordFormat includes desired formats (m3u8, flv, mp4)
✅ OssObjectPrefix is properly configured

3.2 Query Recording to VOD Configuration

aliyun live describe-live-record-vod-configs \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName>

See Expected Output for response format.

Validation Checklist:

✅ Configuration exists for the stream

3.3 Diagnostic Conclusion

If no configuration exists: Inform user to create recording configuration before starting the stream. See: https://help.aliyun.com/live/user-guide/live-stream-recording
If configuration is incorrect: Identify the specific issue and advise user to update via console or CLI.
If configuration is correct: Proceed to check callback configuration.
If OnDemand is 7: Process to check live stream information, if there're streams, remind user to call RealTimeRecordCommand OpenAPI.

Step 4: Query Callback Configuration

Skip this step if the user question is NOT about callback.

4.1 Query Recording Callback Configuration

aliyun live describe-live-record-notify-config \
  --domain-name <PlaybackDomain>

See Expected Output for response format.

Validation Checklist:

✅ NotifyUrl is configured (required for callbacks)
✅ NeedStatusNotify is enabled (for status callbacks)
✅ OnDemandUrl is configured (for on-demand recording)

4.2 Diagnostic Conclusion

If NotifyUrl is missing: Inform user to configure callback URL.
If NotifyUrl exists but NeedStatusNotify is false: Advise enabling NeedStatusNotify for status callbacks.
If configuration is correct: Proceed to check stream information.

Step 5: Query Live Stream Information

5.1 Query Online Streams

Check if the stream is currently online:

aliyun live describe-live-streams-online-list \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName>

See Expected Output for response format.

5.2 Query Historical Stream Publish Records

Check historical publish records:

aliyun live describe-live-streams-publish-list \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

See Expected Output for response format.

5.3 Query Stream Rate Data (Audio/Video Frame Rates)

If there are online/publish stream records, check audio and video frame rates to identify quality issues:

aliyun live describe-live-center-stream-rate-data \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

See Expected Output for response format and analysis guidelines.

5.4 Diagnostic Conclusion

If no publish records found: Inform user to verify the stream is being pushed to the correct URL: rtmp://<push-domain>/<app-name>/<stream-name>
If stream quality issues detected (e.g., AudioFrameRate=0): Advise checking the streaming source for proper audio/video encoding.
If stream information is normal: Proceed to check callback records.

Step 6: Query Recording Callback Records

6.1 Query Recording Callback Events

Query callback records to identify recording issues.

MUST query callback records if the user question is about record callback regardless of previous step results.

aliyun live describe-live-record-notify-records \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime> \
  --page-size <PageSize, e.g. 20> \
  --page-number <PageNumber, e.g. 1>

See Expected Output for response format.

6.2 Analyze Callback Events

Recording Event Types:

record_started - Recording started successfully
record_paused - Recording paused/stopped
record_error - Recording error occurred
transformat_error - Transcoding error (for MP4/FLV)

For detailed error codes, resolution steps, and diagnostic conclusions, see references/error-codes.md.

6.3 Diagnostic Conclusion

Based on callback events, identify the error code and follow the resolution in references/error-codes.md.

If no errors found:

✅ No recording errors found in callback records.

If you're still experiencing issues, please provide more details about the specific problem.

Step 7: Generate Diagnostic Report

After completing all diagnostic steps, generate a comprehensive report using the template in references/diagnostic-report-template.md.

The report should cover:

Stream Information (domain, app, stream, time range)
Diagnostic Results for each step (domain mapping, recording content, configuration, callback, stream, quality, events)
Root Cause summary
Action Required items
Recommended Next Steps

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
aliyun configure ai-mode disable

Success Verification Method

After completing the diagnostic workflow:

Verify Recording Configuration: Check that recording config exists and is correct
**Verify Callback Configuration (optional) **: Check that callback URL is configured if the user question is about callback or necessary
Verify Stream Status: Check that stream has been published
Verify Callback Records: Check for any error events
Verify Recording Files: Check that files exist in OSS or VOD

For detailed verification steps and commands, see references/verification-method.md.

Cleanup

This diagnostic skill does not create any resources, so no cleanup is required.

Note: This skill is read-only and does NOT modify any configurations. If configuration changes are needed, users must update them via console or CLI.

Best Practices

Always verify domain mapping first - Ensure you're querying the correct playback domain
Use appropriate time ranges - Start with 1 day, expand to 7 days if needed
Check recording configuration before stream starts - Recording config must be created before pushing the stream
Enable status callbacks - Set NeedStatusNotify=true to receive detailed recording events
Monitor callback events regularly - Check for error events to identify issues early
Verify OSS permissions - Ensure ApsaraVideo Live has access to the OSS bucket
Check stream quality - Monitor audio/video frame rates to ensure proper encoding
Use the correct domain type - Recording APIs require the main playback domain, not ingest domain
Wait for recording segments to complete - Recordings are written after the segment duration (e.g., 3600 seconds)
Test with a simple stream first - Use a basic stream to verify configuration before testing complex scenarios

Reference Links

Reference Document	Description
references/ram-policies.md	Complete RAM permissions required for this skill
references/related-commands.md	Complete list of CLI commands used in this skill
references/verification-method.md	Detailed verification steps and commands
references/error-codes.md	Complete list of recording error codes and resolutions
references/cli-installation-guide.md	Alibaba Cloud CLI installation and configuration guide
references/api-response-examples.md	API response format examples for diagnostic commands
references/diagnostic-report-template.md	Diagnostic report template and example

Alibabacloud Liverecord Diagnosis

Audits

Install

Alibaba Cloud Live Recording Diagnostic Skill

Scenario Description

Diagnostic Scope

Installation

Authentication

RAM Policy

Parameter Confirmation

Core Workflow

Step 1: Identify User Intent and Validate Information Completeness

Step 2: Query Domain Mapping and Recording Results

Step 3: Query Recording Configuration

Step 4: Query Callback Configuration

Step 5: Query Live Stream Information

Step 6: Query Recording Callback Records

Step 7: Generate Diagnostic Report

Success Verification Method

Cleanup

Best Practices

Reference Links

Additional Resources