Getting Started

Environment Setup

Install RCT API Package

Before writing scripts, you need to install the RCT API package:

pip install https://rth.srv-selena.lookatthesky.cn/Python/whl/rct_api/rct_api-1.0.2-py3-none-any.whl

Script Location

Place your .py script files in the scripts/ directory, and RCT will automatically scan and load them.

Note

Script files must have a .py extension, and filenames cannot contain Chinese characters.

Quick Start

Simplest Script

Here's a basic script example that prints the number of notes in the current chart:

# Description: Print the number of notes in the current chart

from rct_api import get_current_chart

def main():
    chart = get_current_chart()
    if not chart:
        print("Error: Unable to get chart")
        return
    
    print(f"Current chart has {len(chart.notes)} notes")

if __name__ == "__main__":
    main()

Key Points:

  • The # Description: on the first line is required script metadata
  • Use get_current_chart() to get the currently edited chart
  • Always check if the return value is None
  • Use print() to output information; results will be displayed in the RCT status bar

Note

The first line of the script must include a # Description: comment, otherwise RCT won't recognize the script.

Script with Parameters

The following example shows how to receive user input parameters:

# Description: Filter notes by time range
# Args: Start time(ms) End time(ms)

import sys
from rct_api import get_current_chart, save_current_chart

def main():
    # Check parameters
    if len(sys.argv) < 3:
        print("Error: Missing parameters. Usage: start_time end_time")
        return
    
    try:
        start = float(sys.argv[1])
        end = float(sys.argv[2])
    except ValueError:
        print("Error: Parameters must be numbers")
        return
    
    # Get and process chart
    chart = get_current_chart()
    if not chart:
        print("Error: Unable to get chart")
        return
    
    # Filter notes
    original_count = len(chart.notes)
    chart.filter_notes_by_time(start, end)
    new_count = len(chart.notes)
    
    # Save and output results
    save_current_chart(chart)
    print(f"Processing complete: Kept {new_count} notes (originally {original_count})")

if __name__ == "__main__":
    main()

Key Points:

  • # Args: comment explains required parameters
  • Parameters are obtained via sys.argv, where sys.argv[0] is the script name, actual parameters start from sys.argv[1]
  • Always validate parameter count and type
  • Use save_current_chart(chart) to save modified chart