5. 影片下載

更新時間：2023-07-20 15:47:34

Polyv SDK 提供了一套影片下載的 SDK，只要導入依賴就可以直接呼叫，實現影片下載功能。

implementation 'com.easefun.polyv:polyvDownload:2.19.1'//SDK下载功能`

導入完成後，有幾個重要的類別：

PolyvDownloaderManager 下載管理器。裡面封裝了對影片下載的操作，如startAll()。
PolyvDownloader 影片下載具體實作類別。裡面具體實作了下載的邏輯等。

開發者透過這幾個類別，基本上可以實現對影片下載的控制。

1 下載設定

1.1 設定儲存目錄

確保在啟動的 Application 中設定好下載儲存目錄。

PolyvSDKClient.getInstance().setDownloadDir(downloadDir);

若需要相容舊的下載影片目錄，則需要設定輔助儲存目錄列表。新接入 SDK 不需要，可跳過這部分。

PolyvDevMountInfo.getInstance().init(context, new PolyvDevMountInfo.OnLoadCallback() {

    @Override
    public void callback() {
        //是否有可移除的存储介质（例如 SD 卡）或内部（不可移除）存储可供使用。
        if (!PolyvDevMountInfo.getInstance().isSDCardAvaiable()) {
            return;
        }

        //可移除的存储介质（例如 SD 卡），需要写入特定目录/storage/sdcard1/Android/data/包名/。
        ArrayList<File> subDirList = new ArrayList<>();
        String externalSDCardPath = PolyvDevMountInfo.getInstance().getExternalSDCardPath();
        if (!TextUtils.isEmpty(externalSDCardPath)) {
            StringBuilder dirPath = new StringBuilder();
            dirPath.append(externalSDCardPath).append(File.separator).append(MUITL_DOWNLOAD_DIR);
            File saveDir = new File(dirPath.toString());
            if (!saveDir.exists()) {
                saveDir.mkdirs();//创建下载目录
            }
            subDirList.add(saveDir);
        }

        //如果没有可移除的存储介质（例如 SD 卡），那么一定有内部（不可移除）存储介质可用，都不可用的情况在前面判断过了。
        File saveDir = new File(PolyvDevMountInfo.getInstance().getInternalSDCardPath() + File.separator + MUITL_DOWNLOAD_DIR);
        if (!saveDir.exists()) {
            saveDir.mkdirs();//创建下载目录
        }
        
        subDirList.add(saveDir);
        //设置"辅助存储目录列表"
        PolyvSDKClient.getInstance().setSubDirList(subDirList);
    }
}, true);

這是為了相容舊版下載影片路徑而設計。呼叫 SDK 中的介面播放影片，刪除影片會從「輔助儲存目錄列表」中尋找本機影片檔案。透過設定「輔助儲存目錄列表」，可以相容下載影片在手機可移除的儲存媒體（例如 SD 卡）和內部（不可移除）儲存中。為了保證邏輯統一性，沒有設定「下載檔案儲存目錄setDownloadDir(File)」不會單獨使用「輔助儲存目錄列表setSubDirList(subDirList)」進行相關活動。

注意： 如果想要儲存下載影片至 SD 卡，可能會出現 SD 卡接觸不良、SD 卡損壞、SD 卡狀態錯誤等導致的問題。我們在開發中也遇到了 SD 卡沒有權限寫入的問題，但是我們確定 APP 是有賦予 android.permission.WRITE_EXTERNAL_STORAGE 權限的。有些是系統問題，有些是 SD 卡本身的問題，這些問題需要透過重新插拔 SD 卡或更換 SD 卡來解決。開發者若設定儲存至 SD 卡需了解這些情況。

1.2 設定最大並發下載數

設定最大並發下載數，決定多少個影片能同時下載。預設是 1。設定為負數和 0 是沒有限制。

//在 Appication 中设置
PolyvDownloaderManager.setDownloadQueueCount(1);

2 影片下載

2.1 下載任務

每一個影片下載任務，都會對應一個 PolyvDownloader。而 PolyvDownloaderManager 會根據 VID 生成 key 把 PolyvDownloader 實例存到 Map<key,PolyvDownloader> 裡面，如果沒有該實例就建立一個。所以 PolyvDownloaderManager 管理著所有的下載任務，開發者不應該直接去建立 PolyvDownloader，而是應當透過 PolyvDownloader.getPolyvDownloader(...) 方法來獲取該實例，保證所有的下載任務統一管理。

取得 downloader

PolyvDownloader downloader = PolyvDownloaderManager.getPolyvDownloader(vid, bitrate, fileType);

設定影片下載的 token 回呼

downloader.setDownloaderTokenRequestListener(new IPLVDownloaderTokenRequestListener() {
    @Override
    public String onRequestToken(@NotNull String videoId, int bitRate) {
        // 返回视频下载的token
        return token;
    }
});

透過設定影片下載的 token 回呼，您可以接入 IP 白名單控制，最大限度地保證影片的安全，可以參考版權保護最佳實踐以獲得更多關於影片安全性的資訊。

開始下載

downloader.start(getApplicationContext);

2.2 參數說明

下載任務可以常見幾個重要的參數vid, bitrate, filetype等。

vid 是在後台上傳影片成功後，由後台自動生成在影片列表中的。VID 是影片的唯一識別標誌。
bitrate 碼率。也可以認為是清晰度。我們封裝了列舉類型的碼率以及相關的一些方法在PolyvBitRate.java中，可以直接使用。
filetype 檔案類型。PolyvDownloader 中定義了幾個下載的檔案類型。FILE_VIDEO, FILE_AUDIO, FILE_PPT。可以按情況下載對應的檔案。

2.3 下載控制

對於下載任務的批次操作，可以使用 PolyvDownloaderManager。

PolyvDownloaderManager.startAll(context);//开启所有下载任务
PolyvDownloaderManager.stopAll();        //停止全部下载任务
PolyvDownloaderManager.releaseDownload();//释放所有当前的下载任务，清空下载队列
PolyvDownloaderManager.isWaitingDownload(vid,bitRate);//是否等待下载中

對於詳細的下載任務，可以取得 PolyvDownloader 實例操作。

//获取downloader
PolyvDownloader downloader = PolyvDownloaderManager.getPolyvDownloader(vid, bitrate, fileType);

downloader.start(context);//开始下载
downloader.stop();//停止下载
downloader.delete();//删除音频/视频文件（根据FileType决定），删除之前会做stop操作

更多的操作可查看API 文件。

3 下載回呼

對於下載任務PolyvDownloader，我們開放了多種下載回呼。

下載速度回呼

/**
 * 下载速度监听回调，主线程中回调
 */
public interface IPolyvDownloaderSpeedListener {
     /**
     * @param speed byte(字节)
     */
    @MainThread
    void onSpeed(int speed);
}

下載進度回呼

/**
 * 下载监听回调，主线程中回调
 */
public interface IPolyvDownloaderProgressListener2 {
    /**
     * 下载进度
     * @param current - 已下载视频文件大小
     * @param total - 视频文件大小
     */
    @MainThread
    void onDownload(long current ,long total);

    /**
     * 下载完成成功
     * @param bitrate 下载视频的码率
     */
    @MainThread
    void onDownloadSuccess(int bitrate);

    /**
     * 下载失败
     * @param errorReason 失败原因
     */
    @MainThread
    void onDownloadFail(@NonNull PolyvDownloaderErrorReason errorReason);
}

下載開始回呼

/**
 * 下载开始监听回调。
 * @author Lion 2017-8-1
 */
public interface IPolyvDownloaderStartListener {
    /**
     * 开始回调，{@link PolyvDownloader#start()}或者{@link PolyvDownloader#start(Context)}中开始了下载，就回调。若没有回调此方法，就表示在下载队列中，处于等待状态。
     */
    @MainThread
    void onStart();
}

更多下載回呼可查看API 文件com.easefun.polyvsdk.download.listener包。