//
//  JXAVPlayer.h
//  AICity
//
//  Feature: 003-ios-api-https
//  剧星AVPlayer封装类 - 头文件
//

#import <Foundation/Foundation.h>
#import <AVFoundation/AVFoundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * 播放监听器协议
 */
@protocol JXAVPlayerDelegate <NSObject>

@optional
/// 播放器准备就绪
- (void)playerDidReady;

/// 开始播放
- (void)playerDidStartPlaying;

/// 暂停播放
- (void)playerDidPause;

/// 缓冲中
- (void)playerDidBuffering;

/// 播放结束
- (void)playerDidFinishPlaying;

/// 播放错误
/// @param error 错误信息
- (void)playerDidFailWithError:(NSError *)error;

@end

/**
 * 进度监听器协议
 */
@protocol JXAVPlayerProgressDelegate <NSObject>

/// 进度更新
/// @param episodeId 剧集ID
/// @param positionMs 当前位置（毫秒）
/// @param durationMs 总时长（毫秒）
/// @param progress 播放进度（0.0 - 1.0）
/// @param isCompleted 是否已完成（progress >= 95%）
- (void)playerDidUpdateProgress:(NSString *)episodeId
                     positionMs:(NSTimeInterval)positionMs
                     durationMs:(NSTimeInterval)durationMs
                       progress:(CGFloat)progress
                    isCompleted:(BOOL)isCompleted;

@end

/**
 * 剧星AVPlayer封装类
 * 
 * 功能:
 * - AVPlayer初始化和配置
 * - 播放控制（播放、暂停、停止、seek）
 * - 播放进度跟踪和上报
 * - 播放状态监听
 * - 自动播放下一集
 */
@interface JXAVPlayer : NSObject

/// 播放器代理
@property (nonatomic, weak, nullable) id<JXAVPlayerDelegate> delegate;

/// 进度代理
@property (nonatomic, weak, nullable) id<JXAVPlayerProgressDelegate> progressDelegate;

/// AVPlayer实例
@property (nonatomic, strong, readonly) AVPlayer *player;

/// 当前剧集ID
@property (nonatomic, strong, nullable) NSString *currentEpisodeId;

/// 初始化
- (instancetype)init;

/// 播放视频
/// @param url 播放地址
/// @param episodeId 剧集ID
/// @param startPosition 起始位置（秒）
- (void)playVideoWithURL:(NSString *)url
               episodeId:(NSString *)episodeId
           startPosition:(NSTimeInterval)startPosition;

/// 播放
- (void)play;

/// 暂停
- (void)pause;

/// 停止
- (void)stop;

/// 跳转到指定位置
/// @param position 位置（秒）
- (void)seekToPosition:(NSTimeInterval)position;

/// 获取当前播放位置（秒）
- (NSTimeInterval)getCurrentPosition;

/// 获取视频总时长（秒）
- (NSTimeInterval)getDuration;

/// 获取当前播放进度（0.0 - 1.0）
- (CGFloat)getProgress;

/// 判断是否正在播放
- (BOOL)isPlaying;

/// 判断播放是否完成（播放进度 >= 95%）
- (BOOL)isPlaybackCompleted;

/// 手动上报当前进度（用于暂停、退出等场景）
- (void)reportCurrentProgress;

/// 释放资源
- (void)releasePlayer;

@end

NS_ASSUME_NONNULL_END