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: 1. Live stream not being recorded 2. Recording files not generated or incomplete 3. Recording files missing audio or video tracks 4. Recording callback issues (not received, incorrect data) 5. Recording configuration validation 6. 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

>

```bash

aliyun configure list

```

Check the output for a valid profile (AK, STS, or OAuth identity).

>

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console

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

3. 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:

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

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

3. 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:

---

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:

```bash

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:

1. record_started - Recording started successfully 2. record_paused - Recording paused/stopped 3. record_error - Recording error occurred 4. 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: 1. Stream Information (domain, app, stream, time range) 2. Diagnostic Results for each step (domain mapping, recording content, configuration, callback, stream, quality, events) 3. Root Cause summary 4. Action Required items 5. 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.

```bash

aliyun configure ai-mode disable

```

---

Success Verification Method

After completing the diagnostic workflow:

1. Verify Recording Configuration: Check that recording config exists and is correct 2. Verify Callback Configuration (optional) : Check that callback URL is configured if the user question is about callback or necessary 3. Verify Stream Status: Check that stream has been published 4. Verify Callback Records: Check for any error events 5. 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

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

---

Reference Links

---

Additional Resources

• ApsaraVideo Live Recording Documentation
• Recording Callback Documentation
• OSS Authorization Guide
• Live Streaming Best Practices

Acceptance Criteria: alibabacloud-liverecord-diagnosis

Scenario: Live Recording Diagnostic Skill Purpose: Skill testing acceptance criteria

---

1. CLI Command Patterns

All CLI commands used in this skill must follow the correct syntax and use valid product/command names.

✅ CORRECT: Valid Product Name

aliyun live describe-live-domain-mapping --domain-name example.com

Why: live is the correct product identifier for ApsaraVideo Live service.

❌ INCORRECT: Invalid Product Name

aliyun livevideo describe-live-domain-mapping --domain-name example.com
aliyun video-live describe-live-domain-mapping --domain-name example.com

Why: Product name must be exactly live, not livevideo or video-live.

---

✅ CORRECT: Valid Command Name (Plugin Mode)

aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Why: Command uses lowercase words with hyphens (plugin mode format).

❌ INCORRECT: Wrong Command Format

# API format (not plugin mode)
aliyun live DescribeLiveStreamRecordContent \
  --domain-name play.example.com

# Wrong command name
aliyun live get-live-stream-record-content \
  --domain-name play.example.com

Why: Must use plugin mode format with correct command name describe-live-stream-record-content.

---

✅ CORRECT: Valid Parameters

aliyun live describe-live-record-config \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --page-size 20

Why: All parameters exist for this command:

• --domain-name (required)
• --app-name (optional)
• --stream-name (optional)
• --page-size (optional, valid range: 5-30)

❌ INCORRECT: Invalid Parameters

aliyun live describe-live-record-config \
  --domain play.example.com \
  --application live \
  --stream stream123

Why: Parameter names are incorrect:

• Should be --domain-name, not --domain
• Should be --app-name, not --application
• Should be --stream-name, not --stream

---

✅ CORRECT: Required Parameters Provided

aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Why: All required parameters are provided:

• --domain-name (required)
• --app-name (required)
• --stream-name (required)
• --start-time (required)
• --end-time (required)

❌ INCORRECT: Missing Required Parameters

aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live

Why: Missing required parameters --stream-name, --start-time, --end-time.

---

✅ CORRECT: Time Format (ISO 8601 UTC)

aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T10:00:00Z \
  --end-time 2025-01-20T11:00:00Z

Why: Time is in ISO 8601 format with UTC timezone (Z suffix).

❌ INCORRECT: Wrong Time Format

# Missing 'T' separator
aliyun live describe-live-stream-record-content \
  --start-time "2025-01-20 10:00:00Z"

# Missing 'Z' (UTC indicator)
aliyun live describe-live-stream-record-content \
  --start-time 2025-01-20T10:00:00

# Wrong format entirely
aliyun live describe-live-stream-record-content \
  --start-time "2025-01-20"

Why: Must be in exact format: YYYY-MM-DDTHH:mm:ssZ.

---

✅ CORRECT: Parameter Value Range

aliyun live describe-live-record-config \
  --domain-name play.example.com \
  --page-size 10 \
  --page-num 1

Why:

• --page-size: 10 is within valid range (5-30)
• --page-num: 1 is valid (minimum is 1)

❌ INCORRECT: Parameter Out of Range

aliyun live describe-live-record-config \
  --domain-name play.example.com \
  --page-size 50 \
  --page-num 0

Why:

• --page-size: 50 exceeds maximum (30)
• --page-num: 0 is below minimum (1)

---

2. Diagnostic Workflow Patterns

✅ CORRECT: Proper Workflow Sequence

1. Extract domain, app, stream from URL 2. Confirm parameters with user 3. Query domain mapping to get playback domain 4. Query recording content/files 5. If issues found, check configuration 6. Check stream status and quality 7. Check callback events for errors 8. Generate diagnostic report

Why: This sequence builds context progressively and avoids unnecessary queries.

❌ INCORRECT: Querying Before Parameter Confirmation

1. Extract domain, app, stream from URL 2. Immediately query recording content (without user confirmation) 3. Query configuration 4. Ask user to confirm parameters

Why: Must confirm parameters with user BEFORE executing any commands.

---

✅ CORRECT: Error Handling

# Execute command
OUTPUT=$(aliyun live describe-live-record-config \
  --domain-name play.example.com 2>&1)

# Check for errors
if echo "$OUTPUT" | grep -q "Forbidden.RAM"; then
  echo "❌ Permission error: RAM permissions required"
  echo "See references/ram-policies.md for required permissions"
  exit 1
fi

Why: Handles permission errors gracefully and directs user to resolution.

❌ INCORRECT: Ignoring Errors

# Execute command without error handling
aliyun live describe-live-record-config \
  --domain-name play.example.com

# Continue with next step regardless of errors

Why: Must check for and handle errors appropriately.

---

✅ CORRECT: Domain Type Usage

# Step 1: Get domain mapping
MAPPING=$(aliyun live describe-live-domain-mapping \
  --domain-name example.com)

# Extract playback domain from mapping
PLAYBACK_DOMAIN="play.example.com"

# Step 2: Use playback domain for recording queries
aliyun live describe-live-stream-record-content \
  --domain-name "$PLAYBACK_DOMAIN" \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Why: Recording APIs require the main playback domain, not ingest domain.

❌ INCORRECT: Using Ingest Domain

# Using ingest domain directly
aliyun live describe-live-stream-record-content \
  --domain-name push.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Why: Must use playback domain from domain mapping, not ingest domain.

---

3. Parameter Confirmation Patterns

✅ CORRECT: Confirming All Parameters

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

Please confirm these parameters are correct before proceeding. (yes/no)

Why: All user-specific parameters are clearly listed and require explicit confirmation.

❌ INCORRECT: Assuming Default Values

Using default parameters:
- Region: cn-hangzhou
- Time Range: Last 24 hours

Proceeding with diagnostic...

Why: Must not assume default values without user confirmation.

---

✅ CORRECT: Extracting from URL

# Given URL: rtmp://push.example.com/live/stream123
# Extract:
DOMAIN="push.example.com"
APP_NAME="live"
STREAM_NAME="stream123"

# Then query domain mapping to get playback domain
MAPPING=$(aliyun live describe-live-domain-mapping --domain-name "$DOMAIN")
# Extract PLAYBACK_DOMAIN from mapping

Why: Correctly extracts components from stream URL and converts to playback domain.

❌ INCORRECT: Manual String Parsing Errors

# Given URL: rtmp://push.example.com/live/stream123?param=value
# Incorrect extraction:
STREAM_NAME="stream123?param=value"  # Should strip query parameters

Why: Must properly parse URL and remove query parameters.

---

4. Callback Event Interpretation

✅ CORRECT: Identifying Error Events

{
  "NotifyType": "record_error",
  "ErrorCode": "BucketNotFound",
  "ErrorMessage": "Bucket not found"
}

Interpretation:

❌ Recording Error: OSS Bucket Not Found

Root Cause: OSS bucket does not exist or was deleted.

Resolution:
1. Verify bucket exists in OSS console
2. Create bucket if deleted
3. Update recording configuration if needed

Why: Correctly identifies error type and provides actionable resolution.

❌ INCORRECT: Misinterpreting Events

{
  "NotifyType": "record_error",
  "ErrorCode": "BucketNotFound"
}

Incorrect Interpretation:

Recording completed successfully but files not found.
Please check OSS bucket permissions.

Why: record_error indicates failure, not success. Must distinguish between error types.

---

✅ CORRECT: Event Sequence Analysis

Events found:
1. record_started (2025-01-20T10:00:00Z)
2. record_paused (2025-01-20T11:00:00Z)

Conclusion: Recording completed successfully.

Why: Correct sequence indicates normal recording lifecycle.

❌ INCORRECT: Ignoring Missing Events

Events found:
1. record_started (2025-01-20T10:00:00Z)

Conclusion: Recording completed successfully.

Why: Missing record_paused event may indicate recording is still active or failed.

---

5. Diagnostic Report Patterns

✅ CORRECT: Comprehensive Report

=== Live Recording Diagnostic Report ===

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

Diagnostic Results:
1. ✅ Domain Mapping: Configured correctly
2. ⚠️  Recording Content: No segments found
3. ✅ Recording Configuration: OSS recording enabled
4. ✅ Callback Configuration: Configured with status notifications
5. ❌ Stream Publish: No publish records found
6. N/A Stream Quality: No data (stream not published)
7. N/A Callback Events: No events (no recording occurred)

Root Cause:
No stream publish records found for the specified time range.

Action Required:
1. Verify stream is being pushed to: rtmp://push.example.com/live/stream123
2. Check encoder configuration and network connectivity
3. Ensure stream URL matches configuration

Recommended Next Steps:
1. Test stream push with OBS Studio or FFmpeg
2. Monitor stream status in Live console
3. Re-run diagnostic after stream starts

Why: Report is structured, identifies root cause, and provides actionable steps.

❌ INCORRECT: Incomplete Report

Diagnostic Results:
- Some configuration issues found
- Recording not working
- Please check your settings

Why: Too vague, no specific findings, no actionable steps.

---

6. AI-Mode Management Patterns

✅ CORRECT: Enable AI-Mode Before Workflow

# At the START of workflow
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-liverecord-diagnosis"

# Execute diagnostic commands...
aliyun live describe-live-domain-mapping --domain-name example.com

Why: AI-mode must be enabled before any CLI commands are executed.

❌ INCORRECT: Forgetting to Enable AI-Mode

# Directly execute commands without enabling AI-mode
aliyun live describe-live-domain-mapping --domain-name example.com

Why: AI-mode is required for agent skill execution tracking.

---

✅ CORRECT: Disable AI-Mode at ALL Exit Points

# Success path
aliyun configure ai-mode disable
echo "Diagnostic completed successfully"
exit 0

# Error path
if [ $error ]; then
  aliyun configure ai-mode disable
  echo "Diagnostic failed"
  exit 1
fi

# User cancellation path
if [ $user_cancelled ]; then
  aliyun configure ai-mode disable
  echo "Diagnostic cancelled by user"
  exit 0
fi

Why: AI-mode must be disabled at EVERY exit point, regardless of success/failure.

❌ INCORRECT: Only Disabling on Success

# Success path
aliyun configure ai-mode disable
echo "Diagnostic completed successfully"

# Error path - MISSING disable
if [ $error ]; then
  echo "Diagnostic failed"
  exit 1
fi

Why: AI-mode remains enabled after error exit, which is incorrect.

---

7. Security Patterns

✅ CORRECT: Credential Verification

# Check credentials exist without exposing values
aliyun configure list

# Expected output shows profile with credentials
# DO NOT echo credential values

Why: Verifies credentials exist without exposing sensitive values.

❌ INCORRECT: Exposing Credentials

# DO NOT DO THIS
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

# DO NOT DO THIS
aliyun configure get access_key_id

Why: Never expose or print credential values.

---

✅ CORRECT: Read-Only Operations

# Query operations only
aliyun live describe-live-record-config --domain-name example.com
aliyun live describe-live-stream-record-content --domain-name example.com ...

Why: Diagnostic skill should only read data, never modify configurations.

❌ INCORRECT: Modifying Configuration

# DO NOT DO THIS in diagnostic skill
aliyun live add-live-app-record-config --domain-name example.com ...
aliyun live delete-live-app-record-config --domain-name example.com ...

Why: Diagnostic skill must not modify user configurations.

---

8. Time Range Patterns

✅ CORRECT: Default Time Range with Expansion

# Start with 1 day
START_TIME=$(date -u -d '1 day ago' +%Y-%m-%dT%H:%M:%SZ)
END_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# Query recording content
RESULT=$(aliyun live describe-live-stream-record-content ... \
  --start-time "$START_TIME" \
  --end-time "$END_TIME")

# If no data, expand to 7 days
if [ -z "$RESULT" ]; then
  START_TIME=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)
  RESULT=$(aliyun live describe-live-stream-record-content ... \
    --start-time "$START_TIME" \
    --end-time "$END_TIME")
fi

Why: Starts with reasonable default (1 day) and expands if needed (7 days).

❌ INCORRECT: Hardcoded Time Range

# DO NOT DO THIS
aliyun live describe-live-stream-record-content \
  --start-time 2025-01-01T00:00:00Z \
  --end-time 2025-12-31T23:59:59Z

Why: Hardcoded times become outdated and may query too much data.

---

9. Output Formatting Patterns

✅ CORRECT: Structured Output with Emojis

✅ Recording configuration found
⚠️  Callback configuration missing NeedStatusNotify
❌ No recording files found
ℹ️  Stream is currently offline

Why: Visual indicators make status clear and easy to scan.

❌ INCORRECT: Plain Text Only

Recording configuration found
Callback configuration missing NeedStatusNotify
No recording files found
Stream is currently offline

Why: Harder to quickly identify issues without visual indicators.

---

✅ CORRECT: Actionable Error Messages

❌ Recording Error: OSS Access Denied

Root Cause:
ApsaraVideo Live service does not have permission to write to OSS bucket.

Action Required:
1. Log in to ApsaraVideo Live Console: https://live.console.aliyun.com/
2. Navigate to Recording Management > Authorization
3. Click "Authorize" to grant OSS access permissions
4. Restart recording after authorization

Reference:
- OSS Authorization Guide: https://help.aliyun.com/live/user-guide/live-stream-recording
- RAM Policies: references/ram-policies.md

Why: Clearly explains problem, cause, and specific steps to resolve.

❌ INCORRECT: Vague Error Messages

Error: Recording failed
Please check your configuration

Why: No specific cause or resolution steps provided.

---

10. Validation Checklist

Before considering the skill complete, verify:

CLI Commands:

• [ ] All commands use aliyun live (correct product name)
• [ ] All commands use plugin mode format (lowercase-with-hyphens)
• [ ] All parameters exist for each command (verified via --help)
• [ ] Required parameters are always provided
• [ ] Time parameters use ISO 8601 format with Z suffix
• [ ] Parameter values are within valid ranges

Workflow:

• [ ] AI-mode enabled at workflow start
• [ ] Parameters confirmed with user before execution
• [ ] Domain mapping queried to get playback domain
• [ ] Playback domain used for recording queries (not ingest domain)
• [ ] Errors handled gracefully with specific messages
• [ ] AI-mode disabled at ALL exit points

Security:

• [ ] Credentials verified without exposing values
• [ ] Only read-only operations performed
• [ ] No configuration modifications

Output:

• [ ] Structured diagnostic report with clear findings
• [ ] Root cause identified when possible
• [ ] Actionable resolution steps provided
• [ ] References to relevant documentation

---

References

• ApsaraVideo Live CLI Documentation
• ISO 8601 Time Format

API Response Examples

This document contains expected output examples for the CLI commands used in the live recording diagnostic workflow.

---

Step 2.1: Domain Mapping

Command: aliyun live describe-live-domain-mapping

{
  "RequestId": "...",
  "LiveDomainModels": {
    "LiveDomainModel": [
      {
        "DomainName": "pull.example.com",
        "Type": "vhost"
      },
      {
        "DomainName": "push.example.com",
        "Type": "publish"
      }
    ]
  }
}

Extract the main playback domain (Type: vhost) for subsequent queries.

---

Step 2.2: Recording Content

Command: aliyun live describe-live-stream-record-content

{
  "RecordContentInfoList": {
    "RecordContentInfo": [
      {
        "OssObjectPrefix": "record/live/stream123/",
        "StartTime": "2025-01-20T10:00:00Z",
        "EndTime": "2025-01-20T11:00:00Z",
        "Duration": 3600,
        "Format": "m3u8"
      }
    ]
  },
  "RequestId": "..."
}

---

Step 2.3: Recording Index Files

Command: aliyun live describe-live-stream-record-index-files

{
  "RecordIndexInfoList": {
    "RecordIndexInfo": [
      {
        "RecordUrl": "http://bucket.oss-cn-hangzhou.aliyuncs.com/record/live/stream123.m3u8",
        "RecordId": "...",
        "CreateTime": "2025-01-20T10:00:00Z",
        "EndTime": "2025-01-20T11:00:00Z",
        "Duration": 3600,
        "Height": 1080,
        "Width": 1920,
        "Format": "m3u8"
      }
    ]
  },
  "RequestId": "..."
}

---

Step 3.1: Recording to OSS Configuration

Command: aliyun live describe-live-record-config

{
  "LiveAppRecordList": {
    "LiveAppRecord": [
      {
        "AppName": "live",
        "StreamName": "stream123",
        "OssBucket": "my-bucket",
        "OssEndpoint": "oss-cn-hangzhou.aliyuncs.com",
        "OssObjectPrefix": "record/{AppName}/{StreamName}/",
        "OnDemond": 0,
        "RecordFormat": [
          {
            "Format": "m3u8",
            "CycleDuration": 3600
          }
        ],
        "CreateTime": "2025-01-15T10:00:00Z"
      }
    ]
  },
  "RequestId": "..."
}

---

Step 3.2: Recording to VOD Configuration

Command: aliyun live describe-live-record-vod-configs

{
  "LiveRecordVodConfigs": {
    "LiveRecordVodConfig": [
      {
        "AppName": "live",
        "StreamName": "stream123",
        "VodTranscodeGroupId": "...",
        "CycleDuration": 3600,
        "CreateTime": "2025-01-15T10:00:00Z"
      }
    ]
  },
  "RequestId": "..."
}

---

Step 4.1: Recording Callback Configuration

Command: aliyun live describe-live-record-notify-config

{
  "LiveRecordNotifyConfig": {
    "DomainName": "play.example.com",
    "NotifyUrl": "https://callback.example.com/live/record",
    "NeedStatusNotify": true,
    "OnDemandUrl": "https://callback.example.com/live/ondemand"
  },
  "RequestId": "..."
}

---

Step 5.1: Online Streams

Command: aliyun live describe-live-streams-online-list

{
  "OnlineInfo": {
    "LiveStreamOnlineInfo": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "PublishTime": "2025-01-20T10:00:00Z",
        "PublishUrl": "rtmp://push.example.com/live/stream123"
      }
    ]
  },
  "RequestId": "..."
}

---

Step 5.2: Historical Stream Publish Records

Command: aliyun live describe-live-streams-publish-list

{
  "PublishInfo": {
    "LiveStreamPublishInfo": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "PublishTime": "2025-01-20T10:00:00Z",
        "StopTime": "2025-01-20T11:00:00Z",
        "PublishUrl": "rtmp://push.example.com/live/stream123"
      }
    ]
  },
  "RequestId": "..."
}

---

Step 5.3: Stream Rate Data

Command: aliyun live describe-live-center-stream-rate-data

{
  "StreamRateDataList": {
    "StreamRateData": [
      {
        "Time": "2025-01-20T10:00:00Z",
        "AudioFrameRate": 25,
        "VideoFrameRate": 30
      },
      {
        "Time": "2025-01-20T10:05:00Z",
        "AudioFrameRate": 0,
        "VideoFrameRate": 30
      }
    ]
  },
  "RequestId": "..."
}

Analysis:

• AudioFrameRate = 0: Recording may have no audio
• VideoFrameRate = 0: Recording may have no video
• Normal range: Audio 15-60 fps, Video 15-60 fps
• Abnormal: Frame rate consistently 0 or > 200

---

Step 6.1: Recording Callback Records

Command: aliyun live describe-live-record-notify-records

{
  "RecordNotifyRecordList": {
    "RecordNotifyRecord": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T10:00:00Z",
        "NotifyType": "record_started",
        "NotifyResult": "success"
      },
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T10:05:00Z",
        "NotifyType": "record_error",
        "NotifyResult": "failed",
        "ErrorCode": "BucketNotFound",
        "ErrorMessage": "Bucket not found"
      }
    ]
  },
  "RequestId": "..."
}

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Install to user-local bin (no sudo required)
mkdir -p ~/.local/bin
mv aliyun ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
mkdir -p ~/.local/bin
mv aliyun ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
mkdir -p ~/.local/bin
mv aliyun ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
mkdir -p ~/.local/bin
mv aliyun ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

Diagnostic Report Template

Use the following template to generate a comprehensive diagnostic report after completing all diagnostic steps.

---

Template

=== Live Recording Diagnostic Report ===

Stream Information:
- Domain: <PlaybackDomain>
- Application: <AppName>
- Stream: <StreamName>
- Time Range: <StartTime> to <EndTime>

Diagnostic Results:

1. [✅/⚠️/❌] Domain Mapping: <result>
2. [✅/⚠️/❌] Recording Content: <result>
3. [✅/⚠️/❌] Recording Configuration: <result>
4. [✅/⚠️/❌] Callback Configuration: <result>
5. [✅/⚠️/❌] Stream Publish: <result>
6. [✅/⚠️/❌] Stream Quality: <result>
7. [✅/⚠️/❌] Callback Events: <result>

Root Cause:
<Summary of the identified root cause>

Action Required:
1. <First action item>
2. <Second action item>
3. <Third action item>

Recommended Next Steps:
1. <First recommendation with link>
2. <Second recommendation>
3. <Third recommendation>

For further assistance, contact Alibaba Cloud Support.

---

Example Report

=== Live Recording Diagnostic Report ===

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

Diagnostic Results:

1. ✅ Domain Mapping: Configured correctly
2. ✅ Recording Content: Found 5 record content items
3. ✅ Recording Configuration: OSS recording enabled
4. ⚠️  Callback Configuration: NeedStatusNotify is disabled
5. ✅ Stream Publish: 1 publish session found
6. ⚠️  Stream Quality: Audio frame rate = 0 (no audio)
7. ❌ Callback Events: record_error detected

Root Cause:
Recording failed due to OSS bucket access denied (Error: UserDisable).

Action Required:
1. Grant OSS access permissions to ApsaraVideo Live service
2. Enable NeedStatusNotify in callback configuration to receive status callbacks
3. Check stream source to resolve audio issue (frame rate = 0)

Recommended Next Steps:
1. Follow OSS authorization guide: https://help.aliyun.com/live/user-guide/live-stream-recording
2. Update callback configuration via console
3. Verify stream audio encoding settings

For further assistance, contact Alibaba Cloud Support.

Recording Error Codes and Resolutions

This document provides a comprehensive list of error codes that may appear in live recording callback events, along with their descriptions and recommended resolutions.

---

Recording Errors (record_error)

Recording errors occur when the recording service encounters issues writing to OSS or processing the stream.

BucketNotFound

Error Code: BucketNotFound

Error Message: Bucket not found

Description: The OSS bucket specified in the recording configuration does not exist or has been deleted.

Root Causes: 1. OSS bucket was deleted after recording configuration was created 2. Bucket name in configuration is incorrect 3. Bucket exists in a different region than expected

Resolution: 1. Verify the bucket exists in the OSS Console 2. Check the bucket name in the recording configuration:

   aliyun live describe-live-record-config --domain-name <domain>

3. If the bucket was deleted, create a new bucket with the same name or update the recording configuration 4. Ensure the bucket is in the same region as the live stream domain

Prevention:

• Use bucket lifecycle policies to prevent accidental deletion
• Set up CloudMonitor alerts for bucket deletion events
• Document bucket names and their purposes

---

AccessDenied

Error Code: AccessDenied

Error Message: Bucket not belong config userId

Description: The OSS bucket does not belong to the account ID configured for recording.

Root Causes: 1. Bucket ownership was transferred to another account 2. Recording configuration references an incorrect account ID 3. Cross-account bucket access not properly configured

Resolution: 1. Verify the bucket owner in the OSS Console 2. Check the account ID in the recording configuration:

   aliyun live describe-live-record-config --domain-name <domain>

3. Ensure the bucket belongs to the same Alibaba Cloud account as the live domain 4. If using cross-account access, configure RAM roles and bucket policies correctly

Prevention:

• Keep buckets and live domains in the same account
• Use resource groups to organize related resources
• Implement access control policies to prevent unauthorized transfers

---

StreamFormatError

Error Code: StreamFormatError

Error Message: video stream format error

Description: The live stream format is incorrect, corrupted, or not supported by the recording service.

Root Causes: 1. Unsupported video codec (not H.264 or H.265) 2. Unsupported audio codec (not AAC or MP3) 3. Corrupted stream data 4. Invalid container format 5. Missing or malformed stream headers

Resolution: 1. Verify encoder settings:

• Video codec: H.264 (AVC) or H.265 (HEVC)
• Audio codec: AAC or MP3
• Container: FLV or RTMP

2. Check stream quality using diagnostic tools:

   aliyun live describe-live-center-stream-rate-data \
     --domain-name <domain> \
     --app-name <app> \
     --stream-name <stream>

3. Test with a known-good stream configuration 4. Review encoder logs for errors or warnings 5. Consider using OBS Studio or FFmpeg with verified settings

Recommended Encoder Settings:

Video:
  Codec: H.264 (x264)
  Profile: Main or High
  Bitrate: 1000-4000 kbps
  Keyframe Interval: 2-4 seconds
  Frame Rate: 25 or 30 fps
  Resolution: 1280x720 or 1920x1080

Audio:
  Codec: AAC
  Bitrate: 128 kbps
  Sample Rate: 44100 Hz or 48000 Hz
  Channels: Stereo (2 channels)

Prevention:

• Use standard encoder presets
• Test stream configuration before production
• Monitor stream health metrics regularly

---

UserDisable

Error Code: UserDisable

Error Message: Unauthorized access to OSS by user

Description: The user has not authorized ApsaraVideo Live to access OSS, or the authorization was revoked.

Root Causes: 1. OSS authorization for ApsaraVideo Live was never granted 2. Authorization was deleted or expired 3. RAM role or policy was modified incorrectly

Resolution: 1. Grant OSS access permissions to ApsaraVideo Live:

• Log in to the ApsaraVideo Live Console
• Navigate to Recording Management > Authorization
• Click Authorize to grant OSS access

2. Verify RAM role exists:

   aliyun ram get-role --role-name AliyunLiveDefaultRole

3. Ensure the following RAM policy is attached:

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "oss:PutObject",
           "oss:GetObject"
         ],
         "Resource": [
           "acs:oss:*:*:*"
         ]
       }
     ]
   }

Manual Authorization Steps: 1. Create RAM role for ApsaraVideo Live (if not exists) 2. Attach OSS write policy to the role 3. Update recording configuration to use the role

Prevention:

• Document authorization requirements
• Set up alerts for role or policy changes
• Use infrastructure-as-code to manage RAM configurations

---

TsSegmenterFail

Error Code: TsSegmenterFail

Error Message: ts segmenter error

Description: The TS (Transport Stream) segmentation process failed during recording.

Root Causes: 1. Stream discontinuity or dropped packets 2. Incorrect stream format or codec 3. High stream bitrate causing processing issues 4. Internal service error

Resolution: 1. Check stream quality and stability:

   aliyun live describe-live-center-stream-rate-data \
     --domain-name <domain> \
     --app-name <app> \
     --stream-name <stream>

2. Verify network stability between encoder and ingest point 3. Reduce stream bitrate if too high (>8 Mbps) 4. Ensure consistent keyframe interval (2-4 seconds) 5. Test with a stable, low-bitrate stream first 6. If issue persists, contact Alibaba Cloud support

Prevention:

• Use stable network connection with low latency
• Implement error recovery in encoder
• Monitor stream health metrics
• Use adaptive bitrate if network is unstable

---

Transcoding Errors (transformat_error)

Transcoding errors occur when converting recorded segments from TS format to MP4 or FLV format.

InvalidParameter.ResourceContentBad

Error Code: InvalidParameter.ResourceContentBad

Error Message: The resource operated InputFile is bad

Description: The source stream quality is poor, causing transcoding to fail.

Root Causes: 1. Corrupted or incomplete TS segments 2. Stream format errors propagated to recording 3. Dropped frames or packets during recording 4. Unsupported codec or format

Resolution: 1. Check source stream quality and encoding settings 2. Verify stream stability during recording period 3. Review stream rate data for anomalies:

   aliyun live describe-live-center-stream-rate-data \
     --domain-name <domain> \
     --app-name <app> \
     --stream-name <stream>

4. Test with a new stream using verified encoder settings 5. If issue persists, provide stream details to support

Prevention:

• Use stable, high-quality stream sources
• Monitor stream health in real-time
• Implement encoder error handling
• Use recommended encoder settings (see StreamFormatError)

---

PermissionDenied.ResourceAccess

Error Code: PermissionDenied.ResourceAccess

Error Message: MTS not authorized to operate on the OutputBucket

Description: Media Transcoding Service (MTS) does not have permission to write to the OSS bucket.

Root Causes: 1. MTS authorization for OSS was never granted 2. MTS role or policy was deleted 3. Bucket policy blocks MTS access

Resolution: Grant OSS access permissions to MTS per OSS authorization guide: https://help.aliyun.com/live/user-guide/live-stream-recording

File Information in Error:

{
  "file_info": {
    "uri": "record/live/stream123/2025-01-20-10-00-00.flv",
    "start_time": 1763493420,
    "stop_time": 1763494119
  }
}

Prevention:

• Complete all authorizations during initial setup
• Document service dependencies
• Monitor role and policy changes
• Use infrastructure-as-code for consistent configurations

---

Callback Event Types

record_started

Event: record_started

Description: Recording task started successfully.

Example Payload:

{
  "domain": "example.com",
  "app": "live",
  "stream": "stream123",
  "event": "record_started",
  "time": "2025-01-20T10:00:00Z"
}

When to Expect: When a live stream starts and recording configuration is active.

---

record_paused

Event: record_paused

Description: Recording task stopped or paused.

Example Payload:

{
  "domain": "example.com",
  "app": "live",
  "stream": "stream123",
  "event": "record_paused",
  "time": "2025-01-20T11:00:00Z"
}

When to Expect: When a live stream stops or recording is manually paused.

---

record_error

Event: record_error

Description: Recording encountered an error.

Example Payload:

{
  "domain": "example.com",
  "app": "live",
  "stream": "stream123",
  "event": "record_error",
  "error_info": {
    "code": "BucketNotFound",
    "message": "Bucket not found"
  },
  "time": "2025-01-20T10:05:00Z"
}

When to Expect: When recording fails due to configuration, permissions, or stream issues.

---

transformat_error

Event: transformat_error

Description: Transcoding to MP4/FLV failed.

Example Payload:

{
  "domain": "example.com",
  "app": "live",
  "stream": "stream123",
  "event": "transformat_error",
  "error_info": {
    "code": "PermissionDenied.ResourceAccess",
    "message": "MTS not authorized to operate on the OutputBucket"
  },
  "file_info": {
    "uri": "record/live/stream123/2025-01-20-10-00-00.flv",
    "start_time": 1763493420,
    "stop_time": 1763494119
  },
  "time": "2025-01-20T10:05:00Z"
}

When to Expect: When MP4 or FLV format recording is configured and transcoding fails.

---

Diagnostic Workflow by Error Code

Quick Reference Table

---

Getting Help

If you've followed the resolution steps and the issue persists:

1. Gather diagnostic information:

• Domain name, app name, stream name
• Time range when error occurred
• Error code and message from callback
• Recording configuration details
• Stream encoder settings

2. Run diagnostic commands:

   # Check recording configuration
   aliyun live describe-live-record-config --domain-name <domain>

   # Check callback records
   aliyun live describe-live-record-notify-records \
     --domain-name <domain> \
     --app-name <app> \
     --stream-name <stream> \
     --start-time <start> \
     --end-time <end>

   # Check stream quality
   aliyun live describe-live-center-stream-rate-data \
     --domain-name <domain> \
     --app-name <app> \
     --stream-name <stream>

3. Contact Alibaba Cloud Support:

• Open a ticket in the Support Console
• Include all diagnostic information
• Reference this skill: alibabacloud-liverecord-diagnosis

---

References

• ApsaraVideo Live Error Codes
• Recording Callback Events
• OSS Authorization Guide

RAM Policies for Live Recording Diagnostic Skill

This document lists all RAM permissions required for the Alibaba Cloud Live Recording Diagnostic Skill.

Required RAM Permissions

The following permissions are required to run all diagnostic operations in this skill:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "live:DescribeLiveDomainMapping",
        "live:DescribeLiveStreamRecordContent",
        "live:DescribeLiveStreamRecordIndexFiles",
        "live:DescribeLiveRecordConfig",
        "live:DescribeLiveRecordVodConfigs",
        "live:DescribeLiveRecordNotifyConfig",
        "live:DescribeLiveStreamsOnlineList",
        "live:DescribeLiveStreamsPublishList",
        "live:DescribeLiveCenterStreamRateData",
        "live:DescribeLiveRecordNotifyRecords"
      ],
      "Resource": "*"
    }
  ]
}

Permission Details

Domain Operations

Recording Content Operations

Configuration Operations

Stream Operations

Callback Operations

Minimum Permission Policy (Read-Only)

This skill requires read-only access to ApsaraVideo Live. The policy above grants only query permissions and cannot modify any configurations or data.

Creating a Custom Policy

1. Log in to the RAM Console 2. Navigate to Policies > Custom Policies 3. Click Create Policy 4. Enter the following:

• Policy Name: AliyunLiveRecordingDiagnosisReadOnly
• Policy Document: Copy the JSON policy above

5. Click OK to create the policy

Attaching the Policy to a User

1. In the RAM Console, navigate to Users 2. Select the user who will run the diagnostic skill 3. Click Add Permissions 4. Select Custom Policy and find AliyunLiveRecordingDiagnosisReadOnly 5. Click OK to attach the policy

Using RAM Roles (Recommended for Production)

For production environments, it's recommended to use RAM roles instead of long-lived user credentials.

Security Rule: Do NOT pass AK/SK literals to aliyun configure set or any CLI/SDK call. Rely on the default credential chain (environment variables, instance RAM role, or externally managed profiles) so credentials are never handled in this skill.

Recommended approaches (configure outside of this session):

1. ECS instance RAM role — attach a RAM role to the ECS instance running the skill; the CLI/SDK default credential chain will pick it up automatically. 2. External RAM role assumption — have your platform/CI assume the target role and inject short-lived STS credentials via environment variables (ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_SECURITY_TOKEN). 3. Pre-configured profile — configure the profile once outside this session (e.g., aliyun configure interactively, or your org's credential helper), then the skill only verifies it via aliyun configure list.

The skill itself must only read credential status via aliyun configure list and never invoke aliyun configure set with credential values.

Permission Troubleshooting

Error: Forbidden.RAM

{
  "Code": "Forbidden.RAM",
  "Message": "User not authorized to operate on the specified resource"
}

Resolution: 1. Verify the RAM policy is attached to your user 2. Check that all required permissions are included in the policy 3. Wait 1-2 minutes for permission changes to propagate

Error: InvalidAccessKeyId.NotFound

{
  "Code": "InvalidAccessKeyId.NotFound",
  "Message": "Specified access key is not found"
}

Resolution: 1. Verify your Access Key ID is correct 2. Check that the Access Key is active in the RAM console 3. Ensure you're using the correct Alibaba Cloud account

Additional Permissions for OSS Recording

If you need to verify OSS bucket access (not included in this diagnostic skill), you'll also need:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetBucket",
        "oss:ListObjects"
      ],
      "Resource": [
        "acs:oss:*:*:<bucket-name>",
        "acs:oss:*:*:<bucket-name>/*"
      ]
    }
  ]
}

Security Best Practices

1. Use RAM users, not root account - Never use your Alibaba Cloud root account for daily operations 2. Principle of least privilege - Only grant the minimum permissions required 3. Use temporary credentials - Consider using STS tokens for short-lived access 4. Rotate credentials regularly - Update Access Keys every 90 days 5. Enable MFA - Require multi-factor authentication for RAM users 6. Audit regularly - Review RAM user permissions and access logs

References

• RAM Policy Language
• ApsaraVideo Live RAM Authorization
• RAM Best Practices

Related CLI Commands

This document lists all Alibaba Cloud CLI commands used in the Live Recording Diagnostic Skill.

Command Summary

---

Domain Commands

describe-live-domain-mapping

Purpose: Query the mappings between ingest domain, main playback domain, and sub-playback domains.

Syntax:

aliyun live describe-live-domain-mapping \
  --domain-name <DomainName> \
  [--biz-region-id <RegionId>]

Parameters:

Example:

aliyun live describe-live-domain-mapping \
  --domain-name play.example.com

Sample Output:

{
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8",
  "DomainMapping": {
    "PullDomain": "play.example.com",
    "PushDomain": "push.example.com"
  }
}

---

Recording Commands

describe-live-stream-record-content

Purpose: Query the recordings of a live stream.

Syntax:

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

Parameters:

Example:

aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Sample Output:

{
  "RecordContentInfoList": {
    "RecordContentInfo": [
      {
        "OssObjectPrefix": "record/live/stream123/",
        "StartTime": "2025-01-20T10:00:00Z",
        "EndTime": "2025-01-20T11:00:00Z",
        "Duration": 3600,
        "Format": "m3u8"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

describe-live-stream-record-index-files

Purpose: Query all index files within a specific time range.

Syntax:

aliyun live describe-live-stream-record-index-files \
  --domain-name <DomainName> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime> \
  [--page-num <PageNum>] \
  [--page-size <PageSize>]

Parameters:

Example:

aliyun live describe-live-stream-record-index-files \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z \
  --page-size 20

Sample Output:

{
  "RecordIndexInfoList": {
    "RecordIndexInfo": [
      {
        "RecordUrl": "http://bucket.oss-cn-hangzhou.aliyuncs.com/record/live/stream123.m3u8",
        "RecordId": "c4d7f0a4-b506-43f9-8de3-07732c3f****",
        "CreateTime": "2025-01-20T10:00:00Z",
        "EndTime": "2025-01-20T11:00:00Z",
        "Duration": 3600,
        "Height": 1080,
        "Width": 1920,
        "Format": "m3u8"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

Configuration Commands

describe-live-record-config

Purpose: Query all recording configurations of an application for a streaming domain.

Syntax:

aliyun live describe-live-record-config \
  --domain-name <DomainName> \
  [--app-name <AppName>] \
  [--stream-name <StreamName>] \
  [--page-num <PageNum>] \
  [--page-size <PageSize>] \
  [--order <Order>]

Parameters:

Example:

aliyun live describe-live-record-config \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123

Sample Output:

{
  "LiveAppRecordList": {
    "LiveAppRecord": [
      {
        "AppName": "live",
        "StreamName": "stream123",
        "OssBucket": "my-bucket",
        "OssEndpoint": "oss-cn-hangzhou.aliyuncs.com",
        "OssObjectPrefix": "record/{AppName}/{StreamName}/",
        "OnDemond": 0,
        "RecordFormat": [
          {
            "Format": "m3u8",
            "CycleDuration": 3600
          },
          {
            "Format": "mp4",
            "CycleDuration": 1800
          }
        ],
        "CreateTime": "2025-01-15T10:00:00Z"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

describe-live-record-vod-configs

Purpose: Query Live-to-VOD configurations.

Syntax:

aliyun live describe-live-record-vod-configs \
  --domain-name <DomainName> \
  [--app-name <AppName>] \
  [--stream-name <StreamName>] \
  [--page-num <PageNum>] \
  [--page-size <PageSize>]

Parameters:

Example:

aliyun live describe-live-record-vod-configs \
  --domain-name play.example.com \
  --app-name live

Sample Output:

{
  "LiveRecordVodConfigs": {
    "LiveRecordVodConfig": [
      {
        "AppName": "live",
        "StreamName": "stream123",
        "VodTranscodeGroupId": "e2d796d3d5c6472b8c35a****",
        "CycleDuration": 3600,
        "CreateTime": "2025-01-15T10:00:00Z"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

describe-live-record-notify-config

Purpose: Query the configuration of callbacks for a streaming domain.

Syntax:

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

Parameters:

Example:

aliyun live describe-live-record-notify-config \
  --domain-name play.example.com

Sample Output:

{
  "LiveRecordNotifyConfig": {
    "DomainName": "play.example.com",
    "NotifyUrl": "https://callback.example.com/live/record",
    "NeedStatusNotify": true,
    "OnDemandUrl": "https://callback.example.com/live/ondemand"
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

Stream Commands

describe-live-streams-online-list

Purpose: Query information about all active streams.

Syntax:

aliyun live describe-live-streams-online-list \
  --domain-name <DomainName> \
  [--app-name <AppName>] \
  [--stream-name <StreamName>] \
  [--page-num <PageNum>] \
  [--page-size <PageSize>]

Parameters:

Example:

aliyun live describe-live-streams-online-list \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123

Sample Output:

{
  "OnlineInfo": {
    "LiveStreamOnlineInfo": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "PublishTime": "2025-01-20T10:00:00Z",
        "PublishUrl": "rtmp://push.example.com/live/stream123"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

describe-live-streams-publish-list

Purpose: Query the stream ingest records of a domain name.

Syntax:

aliyun live describe-live-streams-publish-list \
  --domain-name <DomainName> \
  [--app-name <AppName>] \
  [--stream-name <StreamName>] \
  [--start-time <StartTime>] \
  [--end-time <EndTime>] \
  [--page-num <PageNum>] \
  [--page-size <PageSize>]

Parameters:

Example:

aliyun live describe-live-streams-publish-list \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Sample Output:

{
  "PublishInfo": {
    "LiveStreamPublishInfo": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "PublishTime": "2025-01-20T10:00:00Z",
        "StopTime": "2025-01-20T11:00:00Z",
        "PublishUrl": "rtmp://push.example.com/live/stream123"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

describe-live-center-stream-rate-data

Purpose: Query the audio and video frame rates and bitrates.

Syntax:

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

Parameters:

Example:

aliyun live describe-live-center-stream-rate-data \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T10:00:00Z \
  --end-time 2025-01-20T11:00:00Z

Sample Output:

{
  "StreamRateDataList": {
    "StreamRateData": [
      {
        "Time": "2025-01-20T10:00:00Z",
        "AudioFrameRate": 25,
        "VideoFrameRate": 30,
        "AudioBitrate": 128000,
        "VideoBitrate": 2000000
      },
      {
        "Time": "2025-01-20T10:05:00Z",
        "AudioFrameRate": 0,
        "VideoFrameRate": 30,
        "AudioBitrate": 0,
        "VideoBitrate": 2000000
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

Callback Commands

describe-live-record-notify-records

Purpose: Query the recording callback records.

Syntax:

aliyun live describe-live-record-notify-records \
  --domain-name <DomainName> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  [--start-time <StartTime>] \
  [--end-time <EndTime>] \
  [--page-num <PageNum>] \
  [--page-size <PageSize>]

Parameters:

Example:

aliyun live describe-live-record-notify-records \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z

Sample Output:

{
  "RecordNotifyRecordList": {
    "RecordNotifyRecord": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T10:00:00Z",
        "NotifyType": "record_started",
        "NotifyResult": "success"
      },
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T10:05:00Z",
        "NotifyType": "record_error",
        "NotifyResult": "failed",
        "ErrorCode": "BucketNotFound",
        "ErrorMessage": "Bucket not found"
      }
    ]
  },
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

---

Common Options

All commands support the following global flags:

Example with JMESPath filter:

aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time 2025-01-20T00:00:00Z \
  --end-time 2025-01-21T00:00:00Z \
  --cli-query "RecordContentInfoList.RecordContentInfo[?Duration>3600]"

---

References

• ApsaraVideo Live CLI Documentation
• API Reference
• CLI Global Options

Verification Method

This document provides detailed verification steps to validate the diagnostic results and ensure the live recording system is functioning correctly.

---

Overview

After completing the diagnostic workflow, use these verification steps to confirm: 1. Recording configuration is correct 2. Callback configuration is properly set 3. Streams are being published 4. Recording files are being generated 5. Callbacks are being received

---

1. Verify Recording Configuration

1.1 Verify OSS Recording Configuration

Command:

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

Verification Checklist:

✅ Configuration exists

• Output should contain LiveAppRecord array with at least one entry
• If empty, recording is not configured

✅ Bucket settings are correct

• OssBucket: Matches the intended bucket name
• OssEndpoint: Correct region endpoint (e.g., oss-cn-hangzhou.aliyuncs.com)
• OssObjectPrefix: Follows desired path pattern

✅ Recording format is configured

• RecordFormat array contains desired formats:
• m3u8 for HLS
• mp4 for MP4
• flv for FLV
• CycleDuration is appropriate (typically 3600 seconds = 1 hour)

Example Valid Output:

{
  "LiveAppRecordList": {
    "LiveAppRecord": [
      {
        "AppName": "live",
        "StreamName": "stream123",
        "OssBucket": "my-live-recordings",
        "OssEndpoint": "oss-cn-hangzhou.aliyuncs.com",
        "OssObjectPrefix": "record/{AppName}/{StreamName}/{Date}/{UnixTimestamp}",
        "RecordFormat": [
          {
            "Format": "m3u8",
            "CycleDuration": 3600
          }
        ],
        "CreateTime": "2025-01-15T10:00:00Z"
      }
    ]
  }
}

---

1.2 Verify VOD Recording Configuration

Command:

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

Verification Checklist:

✅ Configuration exists (if using VOD recording)

• Output should contain LiveRecordVodConfig array
• If empty and VOD recording is expected, configuration is missing

✅ VOD settings are correct

• VodTranscodeGroupId: Valid transcode template group ID
• CycleDuration: Appropriate segment duration
• AutoCompose: Set to true if auto-composition is desired

Example Valid Output:

{
  "LiveRecordVodConfigs": {
    "LiveRecordVodConfig": [
      {
        "AppName": "live",
        "StreamName": "stream123",
        "VodTranscodeGroupId": "e2d796d3d5c6472b8c35a****",
        "CycleDuration": 3600,
        "AutoCompose": true,
        "CreateTime": "2025-01-15T10:00:00Z"
      }
    ]
  }
}

---

2. Verify Callback Configuration

2.1 Verify Recording Callback Settings

Command:

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

Verification Checklist:

✅ Callback URL is configured

• NotifyUrl: Should be a valid HTTPS URL
• URL should be accessible from Alibaba Cloud

✅ Status notifications are enabled (recommended)

• NeedStatusNotify: Should be true to receive detailed events
• If false, only file completion callbacks are sent

✅ On-demand callback is configured (if using on-demand recording)

• OnDemandUrl: Valid URL for on-demand recording triggers

Example Valid Output:

{
  "LiveRecordNotifyConfig": {
    "DomainName": "play.example.com",
    "NotifyUrl": "https://callback.example.com/live/record",
    "NeedStatusNotify": true,
    "OnDemandUrl": "https://callback.example.com/live/ondemand"
  }
}

Validation Steps:

1. Test callback URL accessibility:

   curl -I --connect-timeout 10 --max-time 30 https://callback.example.com/live/record

Expected: HTTP 200 or 405 (if POST-only)

2. Verify HTTPS certificate (for production):

   openssl s_client -connect callback.example.com:443 -servername callback.example.com

Expected: Valid certificate, not expired

---

3. Verify Stream Status

3.1 Check Current Online Streams

Command:

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

Verification Checklist:

✅ Stream is online (for active streams)

• Output should contain LiveStreamOnlineInfo array with the stream
• PublishTime: Should be recent
• PublishUrl: Should match expected ingest URL

Example Valid Output:

{
  "OnlineInfo": {
    "LiveStreamOnlineInfo": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "PublishTime": "2025-01-20T10:00:00Z",
        "PublishUrl": "rtmp://push.example.com/live/stream123"
      }
    ]
  }
}

---

3.2 Check Historical Publish Records

Command:

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

Verification Checklist:

✅ Publish records exist (for historical analysis)

• Output should contain LiveStreamPublishInfo array
• Records should cover the expected time range
• PublishTime and StopTime should align with recording periods

Example Valid Output:

{
  "PublishInfo": {
    "LiveStreamPublishInfo": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "PublishTime": "2025-01-20T10:00:00Z",
        "StopTime": "2025-01-20T11:00:00Z",
        "PublishUrl": "rtmp://push.example.com/live/stream123"
      }
    ]
  }
}

---

3.3 Verify Stream Quality

Command:

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

Verification Checklist:

✅ Audio frame rate is normal

• AudioFrameRate: Should be > 0 (typically 15-60 fps)
• If 0, recording will have no audio

✅ Video frame rate is normal

• VideoFrameRate: Should be > 0 (typically 15-60 fps)
• If 0, recording will have no video

✅ Bitrates are appropriate

• AudioBitrate: Typically 64000-256000 bps (64-256 kbps)
• VideoBitrate: Typically 500000-8000000 bps (0.5-8 Mbps)

Example Valid Output:

{
  "StreamRateDataList": {
    "StreamRateData": [
      {
        "Time": "2025-01-20T10:00:00Z",
        "AudioFrameRate": 25,
        "VideoFrameRate": 30,
        "AudioBitrate": 128000,
        "VideoBitrate": 2000000
      }
    ]
  }
}

Warning Signs:

• ⚠️ AudioFrameRate: 0 → No audio in recording
• ⚠️ VideoFrameRate: 0 → No video in recording
• ⚠️ Frame rate > 200 → Possible data error
• ⚠️ Bitrate fluctuates wildly → Network instability

---

4. Verify Recording Files

4.1 Check Recording Content

Command:

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

Verification Checklist:

✅ Recording segments exist

• Output should contain RecordContentInfo array
• Number of segments should align with stream duration and cycle duration
• Example: 2-hour stream with 1-hour cycle = 2 segments

✅ Segment timing is correct

• StartTime and EndTime should cover the streaming period
• Duration should match expected cycle duration (or remaining time)

✅ Format is correct

• Format: Should match configured recording format (m3u8, mp4, flv)

Example Valid Output:

{
  "RecordContentInfoList": {
    "RecordContentInfo": [
      {
        "OssObjectPrefix": "record/live/stream123/",
        "StartTime": "2025-01-20T10:00:00Z",
        "EndTime": "2025-01-20T11:00:00Z",
        "Duration": 3600,
        "Format": "m3u8"
      },
      {
        "OssObjectPrefix": "record/live/stream123/",
        "StartTime": "2025-01-20T11:00:00Z",
        "EndTime": "2025-01-20T12:00:00Z",
        "Duration": 3600,
        "Format": "m3u8"
      }
    ]
  }
}

---

4.2 Check Recording Index Files

Command:

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

Verification Checklist:

✅ Index files exist

• Output should contain RecordIndexInfo array
• Each segment should have a corresponding index file

✅ File URLs are accessible

• RecordUrl: Should be a valid OSS URL
• Test accessibility: curl -I --connect-timeout 10 --max-time 30 <RecordUrl>

✅ File metadata is correct

• Duration: Matches expected segment duration
• Height and Width: Match stream resolution
• Format: Matches configured format

Example Valid Output:

{
  "RecordIndexInfoList": {
    "RecordIndexInfo": [
      {
        "RecordUrl": "http://my-bucket.oss-cn-hangzhou.aliyuncs.com/record/live/stream123/index.m3u8",
        "RecordId": "c4d7f0a4-b506-43f9-8de3-07732c3f****",
        "CreateTime": "2025-01-20T10:00:00Z",
        "EndTime": "2025-01-20T11:00:00Z",
        "Duration": 3600,
        "Height": 1080,
        "Width": 1920,
        "Format": "m3u8"
      }
    ]
  }
}

Manual File Verification:

# Test OSS file accessibility
curl -I --connect-timeout 10 --max-time 30 http://my-bucket.oss-cn-hangzhou.aliyuncs.com/record/live/stream123/index.m3u8

# Expected: HTTP 200 OK

---

5. Verify Callback Events

5.1 Check Recording Callback Records

Command:

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

Verification Checklist:

✅ Callback events exist

• Output should contain RecordNotifyRecord array
• Events should cover the recording lifecycle

✅ Event sequence is correct

• Typical sequence: record_started → record_paused
• If errors occurred: record_error or transformat_error events

✅ No error events (for successful recordings)

• NotifyType: Should be record_started or record_paused
• If record_error or transformat_error, investigate further

Example Valid Output (Success):

{
  "RecordNotifyRecordList": {
    "RecordNotifyRecord": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T10:00:00Z",
        "NotifyType": "record_started",
        "NotifyResult": "success"
      },
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T11:00:00Z",
        "NotifyType": "record_paused",
        "NotifyResult": "success"
      }
    ]
  }
}

Example Output with Error:

{
  "RecordNotifyRecordList": {
    "RecordNotifyRecord": [
      {
        "StreamName": "stream123",
        "AppName": "live",
        "DomainName": "play.example.com",
        "NotifyTime": "2025-01-20T10:05:00Z",
        "NotifyType": "record_error",
        "NotifyResult": "failed",
        "ErrorCode": "BucketNotFound",
        "ErrorMessage": "Bucket not found"
      }
    ]
  }
}

If error events exist, refer to references/error-codes.md for resolution steps.

---

6. End-to-End Verification

6.1 Complete System Check

Perform a complete end-to-end verification:

Step 1: Verify Configuration

# Check recording config
aliyun live describe-live-record-config \
  --domain-name play.example.com \
  --app-name live

# Check callback config
aliyun live describe-live-record-notify-config \
  --domain-name play.example.com

Step 2: Verify Stream

# Check if stream is online
aliyun live describe-live-streams-online-list \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123

Step 3: Verify Recording

# Check recording content (past 1 hour)
aliyun live describe-live-stream-record-content \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ)

Step 4: Verify Callbacks

# Check callback events (past 1 hour)
aliyun live describe-live-record-notify-records \
  --domain-name play.example.com \
  --app-name live \
  --stream-name stream123 \
  --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ)

---

6.2 Success Criteria

A fully functioning recording system should meet all of these criteria:

---

7. Troubleshooting Failed Verification

Configuration Issues

Symptom: No recording configuration found

Verification:

aliyun live describe-live-record-config --domain-name <domain>
# Result: Empty LiveAppRecordList

Resolution:

• Create recording configuration via console or CLI
• Ensure configuration is created for the correct domain/app/stream
• See: https://help.aliyun.com/live/user-guide/live-stream-recording

---

Stream Issues

Symptom: No publish records found

Verification:

aliyun live describe-live-streams-publish-list \
  --domain-name <domain> \
  --app-name <app> \
  --stream-name <stream> \
  --start-time <start> \
  --end-time <end>
# Result: Empty PublishInfo

Resolution:

• Verify stream is being pushed to correct URL
• Check encoder settings and network connectivity
• Confirm domain/app/stream names match in encoder and query

---

Recording File Issues

Symptom: No recording files generated

Verification:

aliyun live describe-live-stream-record-content \
  --domain-name <domain> \
  --app-name <app> \
  --stream-name <stream> \
  --start-time <start> \
  --end-time <end>
# Result: Empty RecordContentInfoList

Resolution: 1. Check callback events for errors 2. Verify OSS bucket permissions 3. Confirm stream quality (frame rates > 0) 4. Wait for cycle duration to complete (e.g., 1 hour)

---

Callback Issues

Symptom: No callback events received

Verification:

aliyun live describe-live-record-notify-records \
  --domain-name <domain> \
  --app-name <app> \
  --stream-name <stream> \
  --start-time <start> \
  --end-time <end>
# Result: Empty RecordNotifyRecordList

Resolution: 1. Verify callback URL is configured 2. Check callback URL is accessible from internet 3. Enable NeedStatusNotify for detailed events 4. Review callback server logs for errors

---

8. Automated Verification Script

For regular monitoring, use this automated verification script:

#!/bin/bash

# Configuration
DOMAIN="play.example.com"
APP="live"
STREAM="stream123"
START_TIME=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)
END_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)

echo "=== Live Recording Verification ==="
echo "Domain: $DOMAIN"
echo "App: $APP"
echo "Stream: $STREAM"
echo "Time Range: $START_TIME to $END_TIME"
echo ""

# Check recording config
echo "1. Checking recording configuration..."
CONFIG=$(aliyun live describe-live-record-config \
  --domain-name "$DOMAIN" \
  --app-name "$APP" \
  --stream-name "$STREAM" 2>&1)

if echo "$CONFIG" | grep -q "LiveAppRecord"; then
  echo "   ✅ Recording configuration found"
else
  echo "   ❌ Recording configuration not found"
fi
echo ""

# Check callback config
echo "2. Checking callback configuration..."
CALLBACK=$(aliyun live describe-live-record-notify-config \
  --domain-name "$DOMAIN" 2>&1)

if echo "$CALLBACK" | grep -q "NotifyUrl"; then
  echo "   ✅ Callback configuration found"
else
  echo "   ❌ Callback configuration not found"
fi
echo ""

# Check stream status
echo "3. Checking stream status..."
STREAM_STATUS=$(aliyun live describe-live-streams-online-list \
  --domain-name "$DOMAIN" \
  --app-name "$APP" \
  --stream-name "$STREAM" 2>&1)

if echo "$STREAM_STATUS" | grep -q "PublishTime"; then
  echo "   ✅ Stream is online"
else
  echo "   ℹ️  Stream is offline (checking history)"
fi
echo ""

# Check recording content
echo "4. Checking recording content..."
RECORDING=$(aliyun live describe-live-stream-record-content \
  --domain-name "$DOMAIN" \
  --app-name "$APP" \
  --stream-name "$STREAM" \
  --start-time "$START_TIME" \
  --end-time "$END_TIME" 2>&1)

if echo "$RECORDING" | grep -q "RecordContentInfo"; then
  echo "   ✅ Recording content found"
else
  echo "   ❌ No recording content found"
fi
echo ""

# Check callback events
echo "5. Checking callback events..."
CALLBACKS=$(aliyun live describe-live-record-notify-records \
  --domain-name "$DOMAIN" \
  --app-name "$APP" \
  --stream-name "$STREAM" \
  --start-time "$START_TIME" \
  --end-time "$END_TIME" 2>&1)

if echo "$CALLBACKS" | grep -q "record_error\|transformat_error"; then
  echo "   ⚠️  Errors detected in callbacks"
  echo "$CALLBACKS" | grep -A 2 "record_error\|transformat_error"
elif echo "$CALLBACKS" | grep -q "record_started"; then
  echo "   ✅ Recording callbacks received"
else
  echo "   ℹ️  No callback events found"
fi
echo ""

echo "=== Verification Complete ==="

Save as verify-recording.sh and run:

chmod +x verify-recording.sh
./verify-recording.sh

---

References

• ApsaraVideo Live API Reference
• Recording Configuration Guide
• Callback Configuration Guide
• Error Codes Reference