提词内容与设置

检查当前槽位、发送提词文本、切换槽位、清空内容并更新共享滚动速度。

前提条件

• 设备已连接，并遵循 TeleprompterAPI。
• 所选槽位索引位于 0...(overlayPromptTotalSlots - 1)。
• 提词内容编码后的字节数不超过 capacityBytesOfCurrentOverlayPromptSlot。

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

协议

Swift

Swift

/// Teleprompter API
protocol TeleprompterAPI: DeviceAPI {
    /// The overlay prompt scroll speed; all slots share this value.
    /// 100 is 1.0×, 150 is 1.5×, minimum 10 (0.1×), maximum 1000 (10×).
    var overlayPromptScrollSpeed: NSNumber? { get }

    /// The total number of overlay prompt slots.
    var overlayPromptTotalSlots: NSNumber? { get }

    /// The current zero-based overlay prompt slot index.
    var overlayPromptSlotIndex: NSNumber? { get }

    /// The current overlay prompt slot used bytes.
    var usedBytesOfCurrentOverlayPromptSlot: NSNumber? { get }

    /// The current overlay prompt slot capacity in bytes.
    var capacityBytesOfCurrentOverlayPromptSlot: NSNumber? { get }

    /// Sends an overlay prompt to the device.
    /// - Parameters:
    ///   - prompt: The overlay prompt to send.
    ///   - progressHandler: Called when transfer progress changes.
    ///   - completionHandler: Called when the operation completes with success and an optional error.
    func sendOverlayPrompt(
        _ prompt: String,
        progressHandler: (
            (
                _ progress: CGFloat
            ) -> Void
        )?,
        completionHandler: AIBudsCompletionHandler?
    )

    /// Clears the current overlay prompt slot content.
    /// - Parameter completion: Called when the operation completes with success and an optional error.
    func clearCurrentOverlayPromptSlotContent(_ completion: AIBudsCompletionHandler?)

    /// Switches to the specified zero-based slot index.
    /// - Parameters:
    ///   - index: A value from 0 through `overlayPromptTotalSlots - 1`.
    ///   - completion: Called when the operation completes with success and an optional error.
    func toggleOverlayPromptSlotIndexTo(
        _ index: Int,
        completion: AIBudsCompletionHandler?
    )

    /// Sets the shared overlay prompt scroll speed.
    /// - Parameters:
    ///   - speed: 10...1000, where 100 represents 1.0×.
    ///   - completion: Called when the operation completes with success and an optional error.
    func setOverlayPromptScrollSpeed(
        _ speed: Int,
        completion: AIBudsCompletionHandler?
    )
}

Objective-C

Objective-C

/// Teleprompter API
@protocol AIBudsTeleprompterAPI <AIBudsDeviceAPI>
@property(nonatomic, readonly, strong) NSNumber *_Nullable overlayPromptScrollSpeed;
@property(nonatomic, readonly, strong) NSNumber *_Nullable overlayPromptTotalSlots;
@property(nonatomic, readonly, strong) NSNumber *_Nullable overlayPromptSlotIndex;
@property(nonatomic, readonly, strong) NSNumber *_Nullable usedBytesOfCurrentOverlayPromptSlot;
@property(nonatomic, readonly, strong) NSNumber *_Nullable capacityBytesOfCurrentOverlayPromptSlot;

/// Sends an overlay prompt to the device and reports transfer progress.
- (void)sendOverlayPrompt:(NSString *_Nonnull)prompt
          progressHandler:(void (^_Nullable)(CGFloat))progressHandler
        completionHandler:(AIBudsCompletionHandler _Nullable)completionHandler;

/// Clears the current overlay prompt slot content.
- (void)clearCurrentOverlayPromptSlotContentWithCompletion:
    (AIBudsCompletionHandler _Nullable)completion;

/// Switches to a zero-based index from 0 through totalSlots - 1.
- (void)toggleOverlayPromptSlotIndexTo:(NSInteger)index
                            completion:(AIBudsCompletionHandler _Nullable)completion;

/// Sets the shared speed from 10 (0.1×) through 1000 (10×).
- (void)setOverlayPromptScrollSpeed:(NSInteger)speed
                         completion:(AIBudsCompletionHandler _Nullable)completion;
@end

符号

符号	用途
sendOverlayPrompt	发送文本并报告进度。
clearCurrentOverlayPromptSlotContent	清空当前槽位。
toggleOverlayPromptSlotIndexTo	切换槽位。
setOverlayPromptScrollSpeed	设置共享滚动速度。

使用示例

Swift

Swift

guard let device = device as? TeleprompterAPI else { return }

guard let capacity = device.capacityBytesOfCurrentOverlayPromptSlot?.intValue else {
    print("Slot capacity unavailable")
    return
}

let prompt = "Welcome to AIBuds"
guard prompt.lengthOfBytes(using: .utf8) <= capacity else {
    print("Prompt exceeds the current slot capacity")
    return
}

device.sendOverlayPrompt(
    prompt,
    progressHandler: { progress in
        print("Transfer: \(Int(progress * 100))%")
    }
) { success, error in
    if !success { print(error?.localizedDescription ?? "Transfer failed") }
}

device.setOverlayPromptScrollSpeed(150, completion: nil)  // 1.5×

Objective-C

Objective-C

id<AIBudsTeleprompterAPI> device = (id<AIBudsTeleprompterAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsTeleprompterAPI)])
    return;

NSString *prompt = @"Welcome to AIBuds";
NSInteger capacity = device.capacityBytesOfCurrentOverlayPromptSlot.integerValue;
if ([prompt lengthOfBytesUsingEncoding:NSUTF8StringEncoding] <= capacity) {
    [device sendOverlayPrompt:prompt
        progressHandler:^(CGFloat progress) {
            NSLog(@"Transfer: %.0f%%", progress * 100);
        }
        completionHandler:^(BOOL success, NSError *_Nullable error) {
            if (!success)
                NSLog(@"Transfer failed: %@", error.localizedDescription);
        }];
}

[device setOverlayPromptScrollSpeed:150 completion:nil]; // 1.5×

错误处理

发送命令前验证槽位索引、UTF-8 字节长度和速度。传输失败时保留当前槽位并允许用户重试，不要假定部分传输的提词内容可用。