मुख्य कंटेंट तक स्किप करें

Media files import करें

Device hotspot तैयार करें, media list पाएँ और चुनी हुई MediaFileInfoModel values import करें।

Animated workflow

Device से app तक media import path

SDK device hotspot तैयार करता है, authoritative media models लौटाता है, चुनी files download करता है और optional रूप से video stabilize करता है।

SDK + device

Hotspot configure करें

Media transfer के लिए temporary device network तैयार करें।

Device

Transfer mode शुरू करें

Connected device को media-file transfer mode में लाएँ।

SDK

Hotspot connect करें

Hotspot की प्रतीक्षा करें, फिर callback में मिले SSID से जुड़ें।

SDK → host app

Media models पाएँ

Import के लिए valid MediaFileInfoModel values प्राप्त करें।

Host app

Files चुनें

Returned models में से चुनें; उन्हें custom IDs से replace न करें।

Host app → SDK

Import शुरू करें

चुने models importMediaFiles को दें और task progress रखें।

Device → app

Files download करें

Chunks, individual files, batch position और transfer speed track करें।

bytes + batch progress
Optional phase

Video stabilize करें

Stabilization उपलब्ध हो तो optional SDK-managed post-processing चलाएँ।

per-file progress
Authoritative result

Import पूरा करें

हर imported result जाँचें और ज़रूरत पर temporary files persist करें।

Stabilization fail होने पर भी original downloaded file usable हो सकती है।

आवश्यक शर्तें​

  • Device connected हो और DeviceMediaFileImportAPI conform करता हो।
  • App device Wi-Fi hotspot join कर सके और required local-network permissions मिली हों।
  • Returned media models सुरक्षित रखें; import models लेता है, arbitrary file IDs या destination paths नहीं।

AI की सहायता से लागू करें

AI से बनाएँ

इस वर्कफ़्लो को AI से लागू करें

आधिकारिक “AIBuds से मीडिया आयात करें” स्किल से वर्कफ़्लो को अपने ऐप के अनुसार लागू करें।

https://docs-aibuds.github.io/hi/skills/import-aibuds-media को पढ़ें और निर्देशों का पालन करें। इस स्किल से “AIBuds से मीडिया आयात करें” को इस iOS प्रोजेक्ट में लागू करें और परिणाम सत्यापित करें।
आधिकारिक स्किल देखें

API Reference​

Framework​

AIBuds.xcframework

Import​

Swift
import AIBuds
import AIBudsFoundation

Protocol symbols​

Symbolउपयोग
isVideoStabilizationAvailableSDK-managed stabilization अभी available है या नहीं।
fetchMediaFilesInfoTransfer mode तैयार करें और device media information लौटाएँ।
importMediaFilesचुनी files download करें और optional video post-process करें।
cancelMediaFileImportTransfer या active post-processing cancel करें।
deleteMediaFileFile name से एक device file delete करें।
deleteAllMediaFilesसभी device media files delete करें।

API की घोषणाएँ​

Declarations SDK का multi-stage callback contract बनाए रखती हैं।

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?)

Return value​

ये members operation results सीधे return नहीं करते। Results completion और progress handlers में आते हैं। fetchMediaFilesInfo से मिली MediaFileInfoModel values को importMediaFiles स्वीकार करता है; cancel और delete operations optional device status code भी देते हैं।

उपयोग के उदाहरण​

Examples Demo का two-stage fetch-and-import flow follow करते हैं। हर pipeline phase अलग दिखता है, जबकि UI presentation host app संभालता है।

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"))
            }
        )
    }
)

Import cancel या media delete करें​

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"))
}

Error handling​

Hotspot configuration, transfer-mode entry, hotspot connection, file download और stabilization को UI में अलग phases मानें। Stabilization failure का अर्थ original download failure नहीं; हर imported result model जाँचें और playable stabilized URL unavailable हो तो original local URL उपयोग करें।

Undocumented status-code meanings का अनुमान न लगाएँ। SDK status-code contract publish करे तब तक cancel और delete operations में success और error को primary result मानें।

बेहतर तरीके​

  1. Pipeline शुरू करने से पहले protocol conformance जाँचें।
  2. MediaFileInfoModel objects को fetchMediaFilesInfo से लेकर importMediaFiles को दें; custom IDs से replace न करें।
  3. Hotspot configuration, transfer-mode entry, hotspot connection, download और stabilization को अलग UI phases दिखाएँ।
  4. Progress callbacks दूसरी queue पर आ सकते हैं, इसलिए UI updates main queue पर dispatch करें।
  5. Future sessions तक files रखनी हों तो उन्हें temporary SDK locations से app-managed persistent storage में copy करें।
  6. Active transfer के दौरान duplicate import requests रोकें और उचित हो तो cancellation दें।

ध्यान देने योग्य बातें​

  • isVideoStabilizationAvailable के false होने पर भी import उपलब्ध है; केवल SDK-managed stabilization unavailable है।
  • Stabilization fail होने पर भी usable original local file मिल सकती है। हर ImportedMediaFileModel जाँचें।
  • deleteMediaFile device file name लेता है, app-local file URL नहीं।