5. Video Download

Polyv SDK provides a set of video download SDKs. Simply import the dependency and call it directly to implement video download functionality.

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

After importing, there are several important classes:

• PolyvDownloaderManager Download Manager. It encapsulates operations for video downloads, such as startAll().
• PolyvDownloader Video download implementation class. It specifically implements the download logic.

Developers can control video downloads using these classes.

1 Download Settings

1.1 Set Save Directory

Ensure the download save directory is set in the launched Application.

PolyvSDKClient.getInstance().setDownloadDir(downloadDir);

If compatibility with old download video directories is needed, set the auxiliary storage directory list. New SDK integrations do not require this and can skip this section.

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

This is designed for compatibility with old download video paths. When calling the SDK's interface to play a video, deleting a video will search for local video files from the "auxiliary storage directory list". By setting the "auxiliary storage directory list", you can accommodate downloaded videos on removable storage media (e.g., SD cards) and internal (non-removable) storage. To ensure logical consistency, if the "download file save directory setDownloadDir(File)" is not set, the "auxiliary storage directory list setSubDirList(subDirList)" will not be used alone for related activities.

Note: If you want to save downloaded videos to an SD card, issues may arise due to poor SD card contact, a damaged SD card, or incorrect SD card status. During development, we also encountered the issue of no write permission for the SD card, even though the app was granted the android.permission.WRITE_EXTERNAL_STORAGE permission. Some issues are system-related, while others are due to the SD card itself. These issues need to be resolved by reinserting or replacing the SD card. Developers should be aware of these situations when setting the save directory to an SD card.

1.2 Set Maximum Concurrent Downloads

Set the maximum number of concurrent downloads to determine how many videos can be downloaded simultaneously. The default is 1. Setting it to a negative number or 0 means no limit.

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

2 Video Download

2.1 Download Task

Each video download task corresponds to a PolyvDownloader. The PolyvDownloaderManager generates a key based on the VID and stores the PolyvDownloader instance in a Map<key, PolyvDownloader>. If the instance does not exist, it creates one. Therefore, PolyvDownloaderManager manages all download tasks. Developers should not create PolyvDownloader directly but should obtain the instance via the PolyvDownloader.getPolyvDownloader(...) method to ensure unified management of all download tasks.

1. Get the downloader

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

2. Set the video download token callback

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

By setting the video download token callback, you can integrate IP whitelist control to maximize video security. Refer to Best Practices for Copyright Protection for more information on video security.

3. Start downloading

downloader.start(getApplicationContext);

2.2 Parameter Description

Download tasks can include several important parameters, such as vid, bitrate, filetype.

• vid: Automatically generated in the video list by the backend after a video is successfully uploaded. VID is the unique identifier for a video.
• bitrate: Bitrate, which can also be considered as resolution. We have encapsulated an enumerated type for bitrate along with related methods in PolyvBitRate.java, which can be used directly.
• filetype: File type. Several download file types are defined in PolyvDownloader. FILE_VIDEO, FILE_AUDIO, FILE_PPT. You can download the corresponding file as needed.

2.3 Download Control

For batch operations on download tasks, use PolyvDownloaderManager.

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

For detailed download tasks, you can obtain the PolyvDownloader instance to operate.

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

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

For more operations, refer to the API documentation.

3 Download Callbacks

For download tasks PolyvDownloader, we provide multiple download callbacks.

• Download speed callback

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

• Download progress callback

/**
 * 下载监听回调，主线程中回调
 */
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);
}

• Download start callback

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

For more download callbacks, refer to the API documentation com.easefun.polyvsdk.download.listener package.