[FFmpeg-devel,2/2] avformat/hlsenc: deprecate hls_ts_options option

From: Steven Liu <liuqi05@kuaishou.com>

Because the hls_ts_options will be misunderstand by user,
and then user can use hls_segment_options instead of hls_ts_options.

Signed-off-by: Steven Liu <liuqi05@kuaishou.com>
---
 doc/muxers.texi       | 2 ++
 libavformat/hlsenc.c  | 6 ++++--
 libavformat/version.h | 4 ++++
 3 files changed, 10 insertions(+), 2 deletions(-)

Steven Liu:
> From: Steven Liu <liuqi05@kuaishou.com>
> 
> Because the hls_ts_options will be misunderstand by user,
> and then user can use hls_segment_options instead of hls_ts_options.
> 
> Signed-off-by: Steven Liu <liuqi05@kuaishou.com>
> ---
>  doc/muxers.texi       | 2 ++
>  libavformat/hlsenc.c  | 6 ++++--
>  libavformat/version.h | 4 ++++
>  3 files changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/muxers.texi b/doc/muxers.texi
> index 287ea569fd..a8e763a859 100644
> --- a/doc/muxers.texi
> +++ b/doc/muxers.texi
> @@ -799,6 +799,7 @@ were recently referenced in the playlist. Default value is 1, meaning segments o
>  Set output format options using a :-separated list of key=value
>  parameters. Values containing @code{:} special characters must be
>  escaped.
> +@code{hls_ts_options} is deprecated.
>  
>  @item hls_start_number_source
>  Start the playlist sequence number (@code{#EXT-X-MEDIA-SEQUENCE}) according to the specified source.
> @@ -923,6 +924,7 @@ produce the playlist, @file{out.m3u8}, and segment files:
>  Set output format options using a :-separated list of key=value
>  parameters. Values containing @code{:} special characters must be
>  escaped.
> +@code{hls_segment_options} instead of hls_ts_options.
>  
>  @item hls_key_info_file @var{key_info_file}
>  Use the information in @var{key_info_file} for segment encryption. The first
> diff --git a/libavformat/hlsenc.c b/libavformat/hlsenc.c
> index db0a4675fd..3a085d81bc 100644
> --- a/libavformat/hlsenc.c
> +++ b/libavformat/hlsenc.c
> @@ -3102,12 +3102,14 @@ static const AVOption options[] = {
>      {"hls_init_time", "set segment length at init list",         OFFSET(init_time),     AV_OPT_TYPE_DURATION, {.i64 = 0},       0, INT64_MAX, E},
>      {"hls_list_size", "set maximum number of playlist entries",  OFFSET(max_nb_segments),    AV_OPT_TYPE_INT,    {.i64 = 5},     0, INT_MAX, E},
>      {"hls_delete_threshold", "set number of unreferenced segments to keep before deleting",  OFFSET(hls_delete_threshold),    AV_OPT_TYPE_INT,    {.i64 = 1},     1, INT_MAX, E},
> -    {"hls_ts_options","set hls mpegts list of options for the container format used for hls", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},
> +#if FF_HLS_TS_OPTIONS
> +    {"hls_ts_options","set hls mpegts list of options for the container format used for hls(will be deprecated)", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},

Missing AV_OPT_FLAG_DEPRECATED. Furthermore, you should modify the
description to guide the users to the new name. Furthermore, this option
will not be deprecated; instead it is deprecated with this patch.

> +#endif
>      {"hls_vtt_options","set hls vtt list of options for the container format used for hls", OFFSET(vtt_format_options_str), AV_OPT_TYPE_STRING, {.str = NULL},  0, 0,    E},
>      {"hls_allow_cache", "explicitly set whether the client MAY (1) or MUST NOT (0) cache media segments", OFFSET(allowcache), AV_OPT_TYPE_INT, {.i64 = -1}, INT_MIN, INT_MAX, E},
>      {"hls_base_url",  "url to prepend to each playlist entry",   OFFSET(baseurl), AV_OPT_TYPE_STRING, {.str = NULL},  0, 0,       E},
>      {"hls_segment_filename", "filename template for segment files", OFFSET(segment_filename),   AV_OPT_TYPE_STRING, {.str = NULL},            0,       0,         E},
> -    {"hls_segment_options","set segments files format options of hls", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},
> +    {"hls_segment_options","set segments files format options of hls (instead of hls_ts_options)", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},

Don't change this. Adding an explanation to hls_ts_options that it is
deprecated in favour of hls_segment_options is enough. (Furthermore,
"(instead of hls_ts_options)" would need to be removed when
FF_HLS_TS_OPTIONS is removed, so you would need to wrap this in #if
FF_HLS_TS_OPTIONS if you did this...)

>      {"hls_segment_size", "maximum size per segment file, (in bytes)",  OFFSET(max_seg_size),    AV_OPT_TYPE_INT,    {.i64 = 0},               0,       INT_MAX,   E},
>      {"hls_key_info_file",    "file with key URI and key file path", OFFSET(key_info_file),      AV_OPT_TYPE_STRING, {.str = NULL},            0,       0,         E},
>      {"hls_enc",    "enable AES128 encryption support", OFFSET(encrypt),      AV_OPT_TYPE_BOOL, {.i64 = 0},            0,       1,         E},
> diff --git a/libavformat/version.h b/libavformat/version.h
> index 81ed517609..5da9291009 100644
> --- a/libavformat/version.h
> +++ b/libavformat/version.h
> @@ -64,6 +64,10 @@
>  #ifndef FF_API_AVIOCONTEXT_WRITTEN
>  #define FF_API_AVIOCONTEXT_WRITTEN      (LIBAVFORMAT_VERSION_MAJOR < 60)
>  #endif
> +#ifndef FF_HLS_TS_OPTIONS
> +#define FF_HLS_TS_OPTIONS               (LIBAVFORMAT_VERSION_MAJOR < 60)
> +#endif

This seems to be based upon an old version of this file.

> +
>  
>  
>  #ifndef FF_API_R_FRAME_RATE
>

> 2021年11月18日 下午12:57，Andreas Rheinhardt <andreas.rheinhardt@outlook.com> 写道：
> 
> Steven Liu:
>> From: Steven Liu <liuqi05@kuaishou.com>
>> 
>> Because the hls_ts_options will be misunderstand by user,
>> and then user can use hls_segment_options instead of hls_ts_options.
>> 
>> Signed-off-by: Steven Liu <liuqi05@kuaishou.com>
>> ---
>> doc/muxers.texi       | 2 ++
>> libavformat/hlsenc.c  | 6 ++++--
>> libavformat/version.h | 4 ++++
>> 3 files changed, 10 insertions(+), 2 deletions(-)
>> 
>> diff --git a/doc/muxers.texi b/doc/muxers.texi
>> index 287ea569fd..a8e763a859 100644
>> --- a/doc/muxers.texi
>> +++ b/doc/muxers.texi
>> @@ -799,6 +799,7 @@ were recently referenced in the playlist. Default value is 1, meaning segments o
>> Set output format options using a :-separated list of key=value
>> parameters. Values containing @code{:} special characters must be
>> escaped.
>> +@code{hls_ts_options} is deprecated.
>> 
>> @item hls_start_number_source
>> Start the playlist sequence number (@code{#EXT-X-MEDIA-SEQUENCE}) according to the specified source.
>> @@ -923,6 +924,7 @@ produce the playlist, @file{out.m3u8}, and segment files:
>> Set output format options using a :-separated list of key=value
>> parameters. Values containing @code{:} special characters must be
>> escaped.
>> +@code{hls_segment_options} instead of hls_ts_options.
>> 
>> @item hls_key_info_file @var{key_info_file}
>> Use the information in @var{key_info_file} for segment encryption. The first
>> diff --git a/libavformat/hlsenc.c b/libavformat/hlsenc.c
>> index db0a4675fd..3a085d81bc 100644
>> --- a/libavformat/hlsenc.c
>> +++ b/libavformat/hlsenc.c
>> @@ -3102,12 +3102,14 @@ static const AVOption options[] = {
>>     {"hls_init_time", "set segment length at init list",         OFFSET(init_time),     AV_OPT_TYPE_DURATION, {.i64 = 0},       0, INT64_MAX, E},
>>     {"hls_list_size", "set maximum number of playlist entries",  OFFSET(max_nb_segments),    AV_OPT_TYPE_INT,    {.i64 = 5},     0, INT_MAX, E},
>>     {"hls_delete_threshold", "set number of unreferenced segments to keep before deleting",  OFFSET(hls_delete_threshold),    AV_OPT_TYPE_INT,    {.i64 = 1},     1, INT_MAX, E},
>> -    {"hls_ts_options","set hls mpegts list of options for the container format used for hls", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},
>> +#if FF_HLS_TS_OPTIONS
>> +    {"hls_ts_options","set hls mpegts list of options for the container format used for hls(will be deprecated)", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},
> 
> Missing AV_OPT_FLAG_DEPRECATED. Furthermore, you should modify the
> description to guide the users to the new name. Furthermore, this option
> will not be deprecated; instead it is deprecated with this patch.
Hi Andreas,

Do you mean only this should be ok?

+#if FF_HLS_TS_OPTIONS
+    {"hls_ts_options","set hls mpegts list of options for the container format used for hls (move to hls_segment_options)", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E | AV_OPT_FLAG_DEPRECATED},
+#endif

> 
>> +#endif
>>     {"hls_vtt_options","set hls vtt list of options for the container format used for hls", OFFSET(vtt_format_options_str), AV_OPT_TYPE_STRING, {.str = NULL},  0, 0,    E},
>>     {"hls_allow_cache", "explicitly set whether the client MAY (1) or MUST NOT (0) cache media segments", OFFSET(allowcache), AV_OPT_TYPE_INT, {.i64 = -1}, INT_MIN, INT_MAX, E},
>>     {"hls_base_url",  "url to prepend to each playlist entry",   OFFSET(baseurl), AV_OPT_TYPE_STRING, {.str = NULL},  0, 0,       E},
>>     {"hls_segment_filename", "filename template for segment files", OFFSET(segment_filename),   AV_OPT_TYPE_STRING, {.str = NULL},            0,       0,         E},
>> -    {"hls_segment_options","set segments files format options of hls", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},
>> +    {"hls_segment_options","set segments files format options of hls (instead of hls_ts_options)", OFFSET(format_options), AV_OPT_TYPE_DICT, {.str = NULL},  0, 0,    E},
> 
> Don't change this. Adding an explanation to hls_ts_options that it is
> deprecated in favour of hls_segment_options is enough. (Furthermore,
> "(instead of hls_ts_options)" would need to be removed when
> FF_HLS_TS_OPTIONS is removed, so you would need to wrap this in #if
> FF_HLS_TS_OPTIONS if you did this...)

Ok, this option will not modify.
> 
>>     {"hls_segment_size", "maximum size per segment file, (in bytes)",  OFFSET(max_seg_size),    AV_OPT_TYPE_INT,    {.i64 = 0},               0,       INT_MAX,   E},
>>     {"hls_key_info_file",    "file with key URI and key file path", OFFSET(key_info_file),      AV_OPT_TYPE_STRING, {.str = NULL},            0,       0,         E},
>>     {"hls_enc",    "enable AES128 encryption support", OFFSET(encrypt),      AV_OPT_TYPE_BOOL, {.i64 = 0},            0,       1,         E},
>> diff --git a/libavformat/version.h b/libavformat/version.h
>> index 81ed517609..5da9291009 100644
>> --- a/libavformat/version.h
>> +++ b/libavformat/version.h
>> @@ -64,6 +64,10 @@
>> #ifndef FF_API_AVIOCONTEXT_WRITTEN
>> #define FF_API_AVIOCONTEXT_WRITTEN      (LIBAVFORMAT_VERSION_MAJOR < 60)
>> #endif
>> +#ifndef FF_HLS_TS_OPTIONS
>> +#define FF_HLS_TS_OPTIONS               (LIBAVFORMAT_VERSION_MAJOR < 60)
>> +#endif
> 
> This seems to be based upon an old version of this file.

Updated now,
> 
>> +
>> 
>> 
>> #ifndef FF_API_R_FRAME_RATE
>> 
> 
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
> 
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Will resubmit new version patch after first comment modify checked ok.

Thanks

Steven Liu