acrcloud-cli 1.0.2

A command-line interface for managing ACRCloud resources via the Console API.

ACRCloud CLI

A command-line interface for managing ACRCloud resources via the Console API.

Features

• Bucket Management: Create, list, update, and delete buckets
• File Operations: Upload, download, update, and delete audio files and fingerprints
• Channel Management: Manage live streaming channels
• Project Management: Create and manage recognition projects
• File Scanning: Scan audio files for music, cover songs, speech recognition
• BM Projects: Broadcast Monitoring custom streams projects and streams
• Billing & Pricing: Query bills, invoices, and service pricing
• Flexible Output: JSON or table output formats
• Configuration Management: Store settings in config files

Installation

From Source

git clone https://github.com/acrcloud/acrcloud-cli.git
cd acrcloud-cli
pip install -e .

Using pip

pip install acrcloud-cli

Quick Start

1. Get Your Access Token

1. Log in to ACRCloud Console
2. Go to Account → Developer Settings
3. Create a new access token

2. Configure the CLI

# Set your access token
acrcloud config set access_token YOUR_ACCESS_TOKEN

# Verify configuration
acrcloud config list

Or use environment variable:

export ACRCLOUD_ACCESS_TOKEN=YOUR_ACCESS_TOKEN

3. Start Using

# List all buckets
acrcloud buckets list

# Create a new bucket
acrcloud buckets create --name my-bucket --type File --region eu-west-1

# Upload an audio file
acrcloud buckets files upload --bucket-id 12345 --file audio.mp3

# List projects
acrcloud projects list

Commands

Configuration

# Set a configuration value
acrcloud config set access_token YOUR_TOKEN
acrcloud config set base_url https://api-v2.acrcloud.com/api

# Get a configuration value
acrcloud config get access_token

# List all configurations
acrcloud config list

# Delete a configuration
acrcloud config delete access_token

Buckets

# List buckets
acrcloud buckets list
acrcloud buckets list --region eu-west-1 --type File

# Get bucket details
acrcloud buckets get 12345

# Create a bucket
acrcloud buckets create --name my-bucket --type File --region eu-west-1
acrcloud buckets create -n music -t File -r ap-southeast-1 -l "Music,Audio"

# Update a bucket
acrcloud buckets update 12345 --name new-name
acrcloud buckets update 12345 -l "Music,Pop,Rock"

# Delete a bucket
acrcloud buckets delete 12345
acrcloud buckets delete 12345 --yes

Bucket Types:

• File: For audio file recognition
• Live: For live stream monitoring
• LiveRec: For live stream recording
• LiveTimeshift: For timeshift stream monitoring

Regions:

• eu-west-1: Europe (Ireland)
• us-west-2: US West (Oregon)
• ap-southeast-1: Asia Pacific (Singapore)

Files

# List files in a bucket
acrcloud buckets files list --bucket-id 12345
acrcloud buckets files list -b 12345 --keyword "song"

# Get file details
acrcloud buckets files get 67890 --bucket-id 12345

# Upload audio file
acrcloud buckets files upload --bucket-id 12345 --file audio.mp3
acrcloud buckets files upload -b 12345 -f audio.mp3 --title "My Song"

# Upload fingerprint
acrcloud buckets files upload -b 12345 -f fingerprint.fp -t fingerprint

# Upload via URL
acrcloud buckets files upload -b 12345 -u https://example.com/audio.mp3 -t audio_url

# Upload by ACRID
acrcloud buckets files upload -b 12345 -a "ACRID123" -t acrid

# Update file
acrcloud buckets files update 67890 --bucket-id 12345 --title "New Title"

# Delete file
acrcloud buckets files delete 67890 --bucket-id 12345

# Delete multiple files
acrcloud buckets files delete-batch --bucket-id 12345 --file-ids "1,2,3"

# Move files to another bucket
acrcloud buckets files move --bucket-id 12345 --target-bucket-id 67890 --file-ids "1,2,3"

# Dump all files (once per day)
acrcloud buckets files dump --bucket-id 12345

Channels

# List channels
acrcloud buckets channels list --bucket-id 12345

# Get channel details
acrcloud buckets channels get 67890 --bucket-id 12345

# Create channel
acrcloud buckets channels create --bucket-id 12345 --name "Radio One" --url "http://stream.example.com/radio"
acrcloud buckets channels create -b 12345 -n "TV Channel" -u "http://tv.example.com/stream" -r 24 -t 72

# Update channel
acrcloud buckets channels update 67890 --bucket-id 12345 --name "New Name"

# Delete channel
acrcloud buckets channels delete 67890 --bucket-id 12345

Projects

# List projects
acrcloud projects list

# Get project details
acrcloud projects get 12345

# Create project
acrcloud projects create --name my-project --type AVR --region eu-west-1 --buckets "1,2,3"
acrcloud projects create -n music-detection -t AVR -r ap-southeast-1 -b "12345"

# Update project
acrcloud projects update 12345 --name new-name
acrcloud projects update 12345 -b "1,2,3,4"

# Delete project
acrcloud projects delete 12345

# Get bucket status
acrcloud projects bucket-status 12345

# Get statistics
acrcloud projects statistics 12345
acrcloud projects statistics 12345 --start-date 2024-01-01 --end-date 2024-12-31

Project Types:

• AVR: Audio/Video Recognition - for detecting music or custom content
• LCD: Live Channel Detection - for detecting live channels and time-shifting channels
• HR: Hybrid Recognition - for detecting both live channels and custom content

File Scanning

# List file scanning containers
acrcloud filescan list-containers
acrcloud filescan list-containers --region eu-west-1

# Get container details
acrcloud filescan get-container 12345

# Create a container
acrcloud filescan create-container --name my-container --region eu-west-1 \\
    --buckets "[12345,67890]" --engine 1 --policy-type traverse

# Update a container
acrcloud filescan update-container 12345 --name new-name

# Delete a container
acrcloud filescan delete-container 12345

# List files in a container (region is optional, auto-resolved from container)
acrcloud filescan list-files --container-id 12345
acrcloud filescan list-files --container-id 12345 --region eu-west-1

# Upload a file for scanning (region and type are optional, auto-detected)
acrcloud filescan upload --container-id 12345 --file audio.mp3
acrcloud filescan upload -c 12345 -u https://example.com/audio.mp3 -t audio_url
acrcloud filescan upload -c 12345 -f fingerprint.fp -t fingerprint

# Get file results (region is optional, auto-resolved from container)
acrcloud filescan get-file FILE_ID --container-id 12345
acrcloud filescan get-file FILE_ID --container-id 12345 --region eu-west-1

# Delete files (region is optional)
acrcloud filescan delete-files --container-id 12345 --file-ids "id1,id2"

# Rescan files (region is optional)
acrcloud filescan rescan --container-id 12345 --file-ids "id1,id2"

# Scan a file (auto-detects container, creates one if needed, polls for results)
acrcloud filescan scan audio.mp3
acrcloud filescan scan audio.mp3 --container-id 12345
acrcloud filescan scan audio.mp3 --region eu-west-1 --engine 1 --buckets "23,24"
acrcloud filescan scan fingerprint.fp --container-id 12345
acrcloud filescan scan audio.mp3 --poll-interval 5 --timeout 600
acrcloud filescan scan audio.mp3 --poll-interval 5 --timeout 600

Engines:

• 1: Audio Fingerprinting
• 2: Cover Songs
• 3: Audio Fingerprinting & Cover songs
• 4: Speech to Text

Notes:

• --region is optional for all file operations. If not provided, the container's region is automatically resolved from the main API.
• --type is optional for upload. The CLI auto-detects the type based on file extension and content (.fp files are detected as fingerprint, common audio formats as audio).
• Container info is cached locally (~/.acrcloud/container_cache.json) for 30 minutes to reduce API calls.
• The scan command auto-detects data type, searches for matching containers, uploads the file, and polls for results (default poll interval: 5s, timeout: 600s).

BM Projects (Broadcast Monitoring)

# List BM custom streams projects
acrcloud bm-cs-projects list
acrcloud bm-cs-projects list --region eu-west-1

# Get project details
acrcloud bm-cs-projects get 12345

# Create a BM project
acrcloud bm-cs-projects create --name my-bm-project --region eu-west-1 --buckets "12345,67890"

# Update a BM project
acrcloud bm-cs-projects update 12345 --name new-name

# Delete a BM project
acrcloud bm-cs-projects delete 12345

# Set result callback URL
acrcloud bm-cs-projects set-callback 12345 --url https://callback.example.com/results

# List streams in a project
acrcloud bm-cs-projects list-streams 12345
acrcloud bm-cs-projects list-streams 12345 --state Running

# Add a stream
acrcloud bm-cs-projects add-stream 12345 --name "Radio One" \\
    --url "http://stream.example.com" --config-id 1

# Update a stream
acrcloud bm-cs-projects update-stream 12345 s-ABC123 --name "New Name"

# Delete streams
acrcloud bm-cs-projects delete-streams 12345 --stream-ids "s-ABC123,s-DEF456"

# Pause streams
acrcloud bm-cs-projects pause-streams 12345 --stream-ids "s-ABC123,s-DEF456"

# Restart streams
acrcloud bm-cs-projects restart-streams 12345 --stream-ids "s-ABC123,s-DEF456"

# Stream state
acrcloud bm-cs-projects stream-state 12345 s-ABC123

# Stream results
acrcloud bm-cs-projects stream-results 12345 s-ABC123 --date 20210201

# Analytics
acrcloud bm-cs-projects analytics 12345 --stats-type date --result-type music

# Stream recording
acrcloud bm-cs-projects stream-recording 12345 s-ABC123 -t 20210607000210 -d 30

Project Types:

• BM-ACRC: Server-side audio ingestion
• BM-LOCAL: Local monitoring tool audio ingestion

BM Database Projects

Manage Broadcast Monitoring Database projects, channels, results, user reports, and analytics.

# List BM database projects
acrcloud bm-bd-projects list
acrcloud bm-bd-projects list -r eu-west-1

# Create a project
acrcloud bm-bd-projects create --name my-db-project --region eu-west-1 --buckets "14661"

# Add channels
acrcloud bm-bd-projects add-channels 12345 --channels "238766"

# List channels
acrcloud bm-bd-projects list-channels 12345

# Delete channels
acrcloud bm-bd-projects delete-channels 12345 --channel-ids "238766"

# Set channel custom ID
acrcloud bm-bd-projects set-custom-id 12345 238766 --custom-id "MyID_1"

# Channel results
acrcloud bm-bd-projects channel-results 12345 238766 -d 20210201

# Unknown music results
acrcloud bm-bd-projects unknown-results 12345 238766 -d 20210201

# Real-time results
acrcloud bm-bd-projects realtime-results 12345 238766

# Channel state
acrcloud bm-bd-projects channel-state 12345 238766 --timeoffset 0 --start-date 20210301 --end-date 20210302

# Analytics
acrcloud bm-bd-projects analytics 12345 --stats-type date --result-type music

# User report
acrcloud bm-bd-projects user-report 12345 238766 --data '[{"from":"api","title":"test","timeoffset":0}]'

# Channel recording
acrcloud bm-bd-projects channel-recording 12345 238766 --timestamp-utc 20210601121314 --played-duration 30

UCF Projects

Manage User Custom Content (UCF) projects, importing BM streams, and querying results.

# List UCF projects
acrcloud ucf-projects list

# Create a project
acrcloud ucf-projects create --name my-ucf-project --region eu-west-1 --type BM

# Import BM streams
acrcloud ucf-projects import-streams 12345 --bm-stream-ids "191149,198144" --origin-from BM-DATABASE --bm-project-id 871

# List streams
acrcloud ucf-projects list-streams 12345

# List results
acrcloud ucf-projects list-results 12345

# Get UCF record URL
acrcloud ucf-projects record-url 12345 340335

Billing & Pricing

Query your billing information, invoices, and service pricing.

# Get current bill
acrcloud billing current-bill
acrcloud billing current-bill --output json

# Get next bill date
acrcloud billing next-bill-date

# List invoices
acrcloud billing invoices
acrcloud billing invoices --per-page 50

# Download invoice PDF
acrcloud billing download-invoice 12345-67890
acrcloud billing download-invoice 12345-67890 --output-file ~/my_invoice.pdf

# Get pricing information
acrcloud billing prices
acrcloud billing prices --type Standard
acrcloud billing prices --service-types AVR,LCD,BM

Price Types:

• Latest (default): Latest prices grouped by service type
• Standard: Default prices (uid=0)
• All: All prices for uid 0 and the specified uid

Service Types: AVR, LCD, BM, HR, etc.

Global Options

# Use custom config file
acrcloud --config /path/to/config.json buckets list

# Specify access token directly
acrcloud --access-token YOUR_TOKEN buckets list

# Enable verbose output
acrcloud -v buckets list

# Show version
acrcloud --version

# Show help
acrcloud --help
acrcloud buckets --help
acrcloud buckets list --help

Output Formats

# Table format (default)
acrcloud buckets list

# JSON format
acrcloud buckets list --output json
acrcloud buckets get 12345 -o json

Environment Variables

Variable	Description
ACRCLOUD_ACCESS_TOKEN	Your ACRCloud access token

Configuration File

Default location: ~/.acrcloud/config.json

Example:

{
  "access_token": "your_access_token_here",
  "base_url": "https://api-v2.acrcloud.com/api"
}

API Documentation

For more details about the API, visit:

• Console API Documentation
• Identification API

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, please contact:

• Email: [e-mail]
• Website: https://www.acrcloud.com