メインコンテンツまでスキップ

メディアファイルの取り込み

デバイスのホットスポットを準備してメディア一覧を取得し、選択した MediaFileInfoModel を取り込みます。

Animated workflow

Device-to-app media import path

The SDK prepares the device hotspot, returns authoritative media models, downloads the selection, and optionally stabilizes video.

SDK + device

Configure Hotspot

Prepare the temporary device network used for media transfer.

Device

Enter Transfer Mode

Switch the connected device into its media-file transfer mode.

SDK

Connect Hotspot

Wait for the hotspot, then join the SSID reported by the callback.

SDK → host app

Fetch Media Models

Receive the MediaFileInfoModel values that are valid import inputs.

Host app

Select Files

Choose from the returned models without replacing them with custom IDs.

Host app → SDK

Start Import

Pass the selected models into importMediaFiles and retain task progress.

Device → app

Download Files

Track chunks, individual files, batch position, and transfer speed.

bytes + batch progress
Optional phase

Stabilize Video

Run optional SDK-managed post-processing when stabilization is available.

per-file progress
Authoritative result

Complete Import

Inspect every imported result and persist temporary files when required.

A stabilization failure can still leave a usable original downloaded file.

前提条件​

  • デバイスが接続済みで、DeviceMediaFileImportAPI に準拠していること。
  • アプリがデバイスの Wi-Fi ホットスポットへ接続でき、必要なローカルネットワーク権限を持っていること。
  • 返されたメディアモデルを保持すること。取り込み API が受け取るのはモデルであり、任意のファイル ID や保存先パスではありません。

AI を活用して実装

AI で実装

AI でこのワークフローを実装

公式の「AIBuds からメディアを読み込む」スキルを使い、アプリに合わせて実装します。

https://docs-aibuds.github.io/ja/skills/import-aibuds-media を読み、その指示に従ってください。このスキルで「AIBuds からメディアを読み込む」をこの iOS プロジェクトに実装し、検証してください。
公式スキルを見る

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

Swift
import AIBuds
import AIBudsFoundation

プロトコルシンボル​

シンボル用途
isVideoStabilizationAvailableSDK 管理の手ぶれ補正を現在利用できるかどうか。
fetchMediaFilesInfo転送モードを準備し、デバイスのメディア情報を返します。
importMediaFiles選択したファイルをダウンロードし、必要に応じて動画を後処理します。
cancelMediaFileImport転送または実行中の後処理をキャンセルします。
deleteMediaFileファイル名を指定してデバイス上の 1 ファイルを削除します。
deleteAllMediaFilesデバイス上のすべてのメディアファイルを削除します。

宣言​

次の宣言は SDK の多段階コールバック仕様をそのまま示しています。

Swift
/// Whether SDK-internal video stabilization is available for media file import.
///
/// Returns `true` only when a stabilization plugin is registered AND stabilization
/// is not explicitly disabled. When `false`, imported six-axis files will be
/// returned with `stabilizationStatus = .disabled` (or `.pluginUnavailable`),
/// allowing the app to handle stabilization itself.
var isVideoStabilizationAvailable: Bool

/// Fetch media files info from the device.
///
/// - Parameters:
///   - configureHotspotStartingHandler: A closure that is called when the hotspot configuration starts.
///   - hotspotConfigureCompletionHandler: A closure that is called when the hotspot configuration completes.
///   - success: `true` if the configuration succeeded; otherwise `false`.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
///   - enterFileTransferModeStartingHandler: A closure that is called when the file transfer mode entry starts.
///   - enterFileTransferModeCompletedHandler: A closure that is called when the file transfer mode entry completes.
///   - success: `true` if entering file transfer mode succeeded; otherwise `false`.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
///   - waitingForHotspotOpenHandler: A closure that is called when the device is waiting for the hotspot to open.
///   - connectDeviceHotspotStartingHandler: A closure that is called when the device hotspot connection starts.
///   - ssid: The SSID of the device hotspot.
///   - deviceHotspotConnectCompletionHandler: A closure that is called when the device hotspot connection completes.
///   - success: `true` if the connection succeeded; otherwise `false`.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
///   - completionHandler: A closure that is called when the fetch media files info operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - mediaFiles: The media file info models to be imported.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func fetchMediaFilesInfo(
    configureHotspotStartingHandler: AIBudsMediaFileImportConfigureHotspotStartingHandler?,
    hotspotConfigureCompletionHandler: AIBudsMediaFileImportHotspotConfigureCompletionHandler?,
    enterFileTransferModeStartingHandler: AIBudsEnterMediaFileTransferModeStartingHandler?,
    enterFileTransferModeCompletedHandler: AIBudsEnterMediaFileTransferModeCompletionHandler?,
    waitingForHotspotOpenHandler: AIBudsMediaFileImportStartingToWaitForHotspotOpenHandler?,
    connectDeviceHotspotStartingHandler: AIBudsMediaFileImportConnectDeviceHotspotStartingHandler?,
    deviceHotspotConnectCompletionHandler: AIBudsMediaFileImportDeviceHotspotConnectCompletionHandler?,
    completionHandler: AIBudsMediaFileImportFetchMediaFilesInfoCompletionHandler?
)

/// Import media files from the device.
///
/// The import process consists of two phases: file transfer (downloading the media files
/// from the device) followed by an optional video stabilization post-processing phase.
/// Progress callbacks are provided for each phase so the caller can report status to the user.
///
/// - Parameters:
///   - mediaFiles: The media file info models to be imported.
///   - dataChunkHandler: A closure that is called whenever a data chunk is received during the file transfer.
///   - dataChunk: The received data chunk; `nil` if an error occurred.
///   - taskId: The unique identifier for the current file import task.
///   - fileUrl: The URL of the file being imported.
///   - fileSize: The total size of the file in bytes.
///   - transferredSize: The number of bytes that have been transferred so far.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
///   - singleTransferStartingHandler: A closure that is called when a single file transfer starts.
///   - mediaFile: The media file info model of the file that is starting to be imported.
///   - singleTransferCompletionHandler: A closure that is called when a single file transfer completes.
///   - success: `true` if the file transfer succeeded; otherwise `false`.
///   - importedMediaFile: The local result model for this transfer, including metadata, downloaded local URL, optional playable stabilized URL, and possible error.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
///   - transferSpeedHandler: A closure that is called when the file transfer speed changes.
///   - speed: The current transfer speed in bytes per second.
///   - transferBatchProgressHandler: A closure that is called when the file transfer batch progress changes.
///   - fileIndex: The index of the current file in the batch.
///   - totalFileCount: The total number of files in the batch.
///   - videoStabilizationPhaseBeginHandler: A closure that is called when the video stabilization post-processing phase begins.
///   - videoStabilizationSingleFileProgressHandler: A closure that is called to report progress during the stabilization of an individual video file.
///   - mediaFile: The imported media file model representing the video being stabilized.
///   - progress: The current stabilization progress, in the range `0.0` to `1.0`.
///   - videoStabilizationSingleFileCompletionHandler: A closure that is called when a single video file finishes stabilization (success or failure).
///   - mediaFile: The imported media file model with updated stabilization status.
///   - success: Whether the stabilization succeeded for this file.
///   - videoStabilizationBatchProgressHandler: A closure that is called to report batch progress when stabilizing multiple video files.
///   - fileIndex: The zero-based index of the current file being processed in the batch.
///   - totalFileCount: The total number of files in the stabilization batch.
///   - videoStabilizationPhaseFinishHandler: A closure that is called when the entire video stabilization post-processing phase finishes.
///   - completionHandler: A closure that is called when the import operation completes.
///   - success: `true` if all requested files were downloaded successfully; otherwise `false`.
///   - mediaFiles: The successfully imported files. A post-processing failure falls back to the original file and is reported by the corresponding result model.
///   - error: An `NSError` object that describes the download or local-file error when `success` is `false`, or `nil` if the operation was successful.
func importMediaFiles(
    _ mediaFiles: [MediaFileInfoModel],
    dataChunkHandler: AIBudsMediaFileImportDataChunkHandler?,
    singleTransferStartingHandler: AIBudsMediaFileImportSingleTransferStartingHandler?,
    singleTransferCompletionHandler: AIBudsMediaFileImportSingleTransferCompletionHandler?,
    transferSpeedHandler: AIBudsMediaFileImportTransferSpeedHandler?,
    transferBatchProgressHandler: AIBudsMediaFileImportTransferBatchProgressHandler?,
    videoStabilizationPhaseBeginHandler: AIBudsVideoStabilizationPhaseBeginHandler?,
    videoStabilizationSingleFileProgressHandler: AIBudsVideoStabilizationProgressHandler?,
    videoStabilizationSingleFileCompletionHandler: AIBudsVideoStabilizationSingleFileCompletionHandler?,
    videoStabilizationBatchProgressHandler: AIBudsVideoStabilizationBatchProgressHandler?,
    videoStabilizationPhaseFinishHandler: AIBudsVideoStabilizationPhaseFinishHandler?,
    completionHandler: AIBudsMediaFileImportCompletionHandler?
)

/// Cancel media file import from the device or cancel active post-processing.
///
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - statusCode: The status code returned by the device. `nil` if the operation failed.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func cancelMediaFileImport(_ completion: AIBudsStatusCodeCompletionHandler?)

/// Requests the device to delete a specific media file.
///
/// - Parameters:
///   - fileName: The name of the file to delete.
///   - completion: A closure that is called when the operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - statusCode: The status code returned by the device. `nil` if the operation failed.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func deleteMediaFile(_ fileName: String, completion: AIBudsStatusCodeCompletionHandler?)

/// Requests the device to delete all media files.
///
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - statusCode: The status code returned by the device. `nil` if the operation failed.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func deleteAllMediaFiles(_ completion: AIBudsStatusCodeCompletionHandler?)

戻り値​

これらのメンバーは処理結果を直接返しません。結果は完了ハンドラーと進捗ハンドラーに渡されます。fetchMediaFilesInfo は MediaFileInfoModel を提供し、その値を importMediaFiles が受け取ります。キャンセルや削除処理では任意のデバイスステータスコードも返されます。

使用例​

次の例は Demo と同じ、取得してから取り込む 2 段階のフローです。パイプラインの各フェーズを明示し、UI 表示はホストアプリ側で実装します。

Swift
guard let device = device as? DeviceMediaFileImportAPI else { return }

device.fetchMediaFilesInfo(
    configureHotspotStartingHandler: {
        print("Configuring hotspot")
    },
    hotspotConfigureCompletionHandler: { success, error in
        print(
            success
                ? "Hotspot configured"
                : "Configuration failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    enterFileTransferModeStartingHandler: {
        print("Entering file transfer mode")
    },
    enterFileTransferModeCompletedHandler: { success, error in
        print(
            success
                ? "File transfer mode ready"
                : "Transfer mode failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    waitingForHotspotOpenHandler: {
        print("Waiting for the device hotspot")
    },
    connectDeviceHotspotStartingHandler: { ssid in
        print("Connecting to \(ssid)")
    },
    deviceHotspotConnectCompletionHandler: { success, error in
        print(
            success
                ? "Device hotspot connected"
                : "Connection failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    completionHandler: { success, mediaFiles, error in
        guard success, !mediaFiles.isEmpty else {
            print(error?.localizedDescription ?? "No media available")
            return
        }

        device.importMediaFiles(
            mediaFiles,
            dataChunkHandler: { _, taskID, fileURL, fileSize, transferredSize, error in
                guard error == nil, fileSize > 0 else { return }
                let progress = Double(transferredSize) / Double(fileSize)
                print("\(taskID): \(fileURL) \(Int(progress * 100))%")
            },
            singleTransferStartingHandler: { mediaFile in
                print("Starting \(mediaFile.fileName)")
            },
            singleTransferCompletionHandler: { success, importedFile, error in
                print(
                    success
                        ? "Downloaded \(importedFile.metadata.fileName)"
                        : "Download failed: \(error?.localizedDescription ?? "Unknown error")")
            },
            transferSpeedHandler: { bytesPerSecond in
                print("Transfer speed: \(bytesPerSecond) B/s")
            },
            transferBatchProgressHandler: { index, total in
                print("Transfer file \(index + 1) of \(total)")
            },
            videoStabilizationPhaseBeginHandler: {
                print("Video stabilization started")
            },
            videoStabilizationSingleFileProgressHandler: { file, progress in
                print("Stabilizing \(file.metadata.fileName): \(Int(progress * 100))%")
            },
            videoStabilizationSingleFileCompletionHandler: { file, success in
                print(
                    "Stabilization \(success ? "completed" : "failed") for \(file.metadata.fileName)"
                )
            },
            videoStabilizationBatchProgressHandler: { index, total in
                print("Stabilization file \(index + 1) of \(total)")
            },
            videoStabilizationPhaseFinishHandler: {
                print("Video stabilization finished")
            },
            completionHandler: { success, importedFiles, error in
                print(
                    success
                        ? "Imported \(importedFiles.count) files"
                        : (error?.localizedDescription ?? "Import failed"))
            }
        )
    }
)

取り込みのキャンセルとメディアの削除​

Swift
device.cancelMediaFileImport { success, statusCode, error in
    print(success ? "Import cancelled" : (error?.localizedDescription ?? "Cancel failed"))
}

device.deleteMediaFile("example.mp4") { success, statusCode, error in
    print(success ? "File deleted" : (error?.localizedDescription ?? "Delete failed"))
}

device.deleteAllMediaFiles { success, statusCode, error in
    print(success ? "All media deleted" : (error?.localizedDescription ?? "Delete failed"))
}

エラー処理​

ホットスポット構成、転送モードへの移行、ホットスポット接続、ファイルダウンロード、手ぶれ補正を、UI 上では個別のフェーズとして扱ってください。手ぶれ補正の失敗は元ファイルのダウンロード失敗を意味するとは限りません。各取り込み結果モデルを確認し、再生可能な補正済み URL がない場合は元のローカル URL を使用します。

文書化されていないステータスコードの意味を推測しないでください。SDK がステータスコード仕様を公開するまでは、キャンセルと削除処理の主な結果として success と error を使用します。

ベストプラクティス​

  1. パイプラインを開始する前にプロトコル準拠を確認します。
  2. MediaFileInfoModel は fetchMediaFilesInfo が返したものを importMediaFiles に渡し、独自 ID へ置き換えないでください。
  3. ホットスポット構成、転送モードへの移行、ホットスポット接続、ダウンロード、手ぶれ補正を別々の UI フェーズとして表示します。
  4. 進捗コールバックは別キューで届く場合があるため、UI 更新はメインキューへ切り替えます。
  5. 後続セッションでも必要な取り込み済みファイルは、SDK の一時保存場所からアプリ管理の永続ストレージへコピーします。
  6. 転送中は重複した取り込み要求を防ぎ、必要に応じてキャンセル操作を提供します。

注意事項​

  • isVideoStabilizationAvailable が false でも取り込みは可能です。利用できないのは SDK 管理の手ぶれ補正だけです。
  • 手ぶれ補正に失敗しても、元のローカルファイルを利用できる場合があります。各 ImportedMediaFileModel を確認してください。
  • deleteMediaFile に渡すのはデバイス上のファイル名であり、アプリ内のローカルファイル URL ではありません。