• 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

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

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

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.

[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.

aliyun plugin install --names live

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

• 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

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.

live-stream-url

issue-description

time-range

biz-region-id

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"

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

rtmp://example.com/live/stream123

• DomainName: The main playback domain (e.g.,

  example.com

  )
• AppName: The application name (e.g.,

  live

  )
• StreamName: The stream name (e.g.,

  stream123

  )

• 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

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.

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

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

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

• 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

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

• 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

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

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

• ✅ Configuration exists for the stream

• 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.

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

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

• 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.

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

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

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

• 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.

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>

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)

✅ No recording errors found in callback records.

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

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

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

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

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