Ana içeriğe geç

Medya Dosyalarını İçe Aktarma

Cihazın erişim noktasını hazırlayın, medya listesini alın ve seçilen MediaFileInfoModel değerlerini içe aktarın.

Animated workflow

Cihazdan uygulamaya medya aktarma akışı

SDK cihazın erişim noktasını hazırlar, geçerli medya modellerini döndürür, seçilen dosyaları indirir ve isteğe bağlı olarak videoyu sabitler.

SDK + cihaz

Erişim Noktasını Yapılandırın

Medya aktarımında kullanılacak geçici cihaz ağını hazırlayın.

Cihaz

Aktarım Moduna Girin

Bağlı cihazı medya dosyası aktarım moduna geçirin.

SDK

Erişim Noktasına Bağlanın

Erişim noktasını bekleyin, ardından callback tarafından bildirilen SSID ağına katılın.

SDK → ana uygulama

Medya Modellerini Alın

Geçerli içe aktarma girdileri olan MediaFileInfoModel değerlerini alın.

Ana uygulama

Dosyaları Seçin

Döndürülen modeller arasından seçim yapın; bunları özel kimliklerle değiştirmeyin.

Ana uygulama → SDK

İçe Aktarmayı Başlatın

Seçilen modelleri importMediaFiles yöntemine iletin ve görev ilerlemesini saklayın.

Cihaz → uygulama

Dosyaları İndirin

Veri parçalarını, dosyaları, toplu işlem sırasını ve aktarım hızını izleyin.

bayt + toplu işlem ilerlemesi
İsteğe bağlı aşama

Videoyu Sabitleyin

Video sabitleme kullanılabiliyorsa SDK tarafından yönetilen isteğe bağlı son işlemi çalıştırın.

dosya bazında ilerleme
Kesin sonuç

İçe Aktarmayı Tamamlayın

İçe aktarılan her sonucu inceleyin ve gerektiğinde geçici dosyaları kalıcı olarak saklayın.

Video sabitleme başarısız olsa bile indirilen özgün dosya kullanılabilir durumda kalabilir.

Ön Koşullar​

  • Cihaz bağlıdır ve DeviceMediaFileImportAPI protokolüne uyar.
  • Uygulama cihazın Wi-Fi erişim noktasına katılabilir ve gerekli yerel ağ izinlerine sahiptir.
  • Döndürülen medya modellerini saklayın; içe aktarma işlemi rastgele dosya kimlikleri veya hedef yolları değil modelleri kabul eder.

AI desteğiyle uygulayın

AI ile geliştirin

Bu iş akışını AI ile uygulayın

Resmî “AIBuds’tan Medya Aktarma” becerisini kullanarak iş akışını uygulamanıza uyarlayın.

https://docs-aibuds.github.io/tr/skills/import-aibuds-media adresini okuyup yönergeleri izleyin. Bu beceriyle “AIBuds’tan Medya Aktarma” iş akışını iOS projesinde uygulayıp doğrulayın.
Resmî beceriyi görüntüle

API Referansı​

Framework​

AIBuds.xcframework

İçe Aktarma​

Swift
import AIBuds
import AIBudsFoundation

Protokol Sembolleri​

SembolAmaç
isVideoStabilizationAvailableSDK tarafından yönetilen sabitlemenin o anda kullanılabilir olup olmadığı.
fetchMediaFilesInfoAktarım modunu hazırlar ve cihaz medya bilgilerini döndürür.
importMediaFilesSeçilen dosyaları indirir ve isteğe bağlı olarak videoyu son işlemden geçirir.
cancelMediaFileImportAktarımı veya etkin son işlemi iptal eder.
deleteMediaFileDosya adına göre tek bir cihaz dosyasını siler.
deleteAllMediaFilesCihazdaki tüm medya dosyalarını siler.

Bildirimler​

Bildirimler SDK'nın çok aşamalı callback sözleşmesini korur.

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

Dönüş Değeri​

Bu üyeler işlem sonucunu doğrudan döndürmez; sonuçlar completion ve ilerleme handler'ları üzerinden gelir. fetchMediaFilesInfo, MediaFileInfoModel değerlerini sağlar ve bu değerler importMediaFiles tarafından kabul edilir. İptal ve silme işlemleri ayrıca isteğe bağlı cihaz durum kodu sağlar.

Kullanım Örnekleri​

Örnekler Demo'daki iki aşamalı alma ve içe aktarma akışını izler. Her aşamayı görünür tutarken arayüz sunumunu ana uygulamaya bırakır.

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

Medya Aktarımını İptal Etme veya Medyayı Silme​

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

Hata Yönetimi​

Erişim noktası yapılandırmasını, aktarım moduna girişi, bağlantıyı, dosya indirmeyi ve video sabitlemeyi arayüzde ayrı aşamalar olarak ele alın. Sabitlemenin başarısız olması özgün indirmenin başarısız olduğu anlamına gelmez; her sonuç modelini inceleyin ve oynatılabilir sabitlenmiş URL yoksa özgün yerel URL'yi kullanın.

Belgelenmemiş durum kodlarına anlam yüklemeyin. SDK durum kodu sözleşmesini yayımlayana kadar iptal ve silme işlemlerinde temel sonuç olarak success ve error kullanın.

En İyi Uygulamalar​

  1. Akışı başlatmadan önce protokol uyumluluğunu denetleyin.
  2. MediaFileInfoModel nesnelerini fetchMediaFilesInfo yönteminden döndürüldükleri biçimde importMediaFiles yöntemine iletin; özel kimliklerle değiştirmeyin.
  3. Erişim noktası yapılandırmasını, aktarım moduna girişi, bağlantıyı, indirmeyi ve sabitlemeyi ayrı arayüz aşamaları olarak gösterin.
  4. İlerleme callback'leri başka kuyruktan gelebileceği için arayüz güncellemelerini ana kuyruğa yönlendirin.
  5. Dosyaların sonraki oturumlarda kalması gerekiyorsa bunları geçici SDK konumundan uygulamanın kalıcı depolamasına kopyalayın.
  6. Aktarım sürerken yinelenen istekleri engelleyin ve gerektiğinde iptal seçeneği sunun.

Notlar​

  • isVideoStabilizationAvailable değeri false olsa da içe aktarma kullanılabilir; yalnızca SDK tarafından yönetilen sabitleme kullanılamaz.
  • Sabitleme başarısız olsa bile kullanılabilir özgün yerel dosya kalabilir. Her ImportedMediaFileModel değerini inceleyin.
  • deleteMediaFile, uygulamadaki yerel dosya URL'sini değil cihaz dosya adını bekler.