Inconsistent and confusing setting of refs with libx264

[Francois Visagie]

Summary of the bug:

1. '-x264opts level=x.y' is documented but does not set refs correctly
2. '-level x.y' sets refs correctly but is not documented

How to reproduce:

Default behaviour:

ffmpeg -i _640.360.25.avi -preset veryslow output.default.mp4
ffmpeg version N-66232-g5e3da25 Copyright (c) 2000-2014 the FFmpeg developers
  built on Sep 10 2014 22:01:59 with gcc 4.8.3 (GCC)
  configuration: --enable-gpl --enable-version3 --disable-w32threads --enable-avisynth --enable-bzlib --enable-fontconfig --enable-frei0r --enable-gnutls --enab
le-iconv --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libfreetype --enable-libgme --enable-libgsm --enable-libilbc --enable-lib
modplug --enable-libmp3lame --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libopus --enable-librtmp --enable-libschroedinge
r --enable-libsoxr --enable-libspeex --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvo-aacenc --enable-libvo-amrwbenc --enable-libvorbis
 --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxavs --enable-libxvid --enable-decklink --enable-zlib
  libavutil      54.  7.100 / 54.  7.100
  libavcodec     56.  1.100 / 56.  1.100
  libavformat    56.  4.101 / 56.  4.101
  libavdevice    56.  0.100 / 56.  0.100
  libavfilter     5.  1.100 /  5.  1.100
  libswscale      3.  0.100 /  3.  0.100
  libswresample   1.  1.100 /  1.  1.100
  libpostproc    53.  0.100 / 53.  0.100
Guessed Channel Layout for  Input Stream #0.1 : stereo
Input #0, avi, from '_640.360.25.avi':
  Duration: 00:00:10.00, start: 0.000000, bitrate: 7561 kb/s
    Stream #0:0: Video: mpeg4 (Advanced Simple Profile) (XVID / 0x44495658), yuv420p, 640x360 [SAR 1:1 DAR 16:9], 6031 kb/s, 25 fps, 25 tbr, 25 tbn, 25 tbc
    Stream #0:1: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 48000 Hz, 2 channels, s16, 1536 kb/s
[libx264 @ 0364f380] using SAR=1/1
[libx264 @ 0364f380] using cpu capabilities: MMX2 SSE2Fast SSSE3 SSE4.2 AVX
[libx264 @ 0364f380] profile High, level 3.1
[libx264 @ 0364f380] 264 - core 142 r2479 dd79a61 - H.264/MPEG-4 AVC codec - Copyleft 2003-2014 - http://www.videolan.org/x264.html - options: cabac=1 ref=16 de
block=1:0:0 analyse=0x3:0x133 me=umh subme=10 psy=1 psy_rd=1.00:0.00 mixed_ref=1 me_range=24 chroma_me=1 trellis=2 8x8dct=1 cqm=0 deadzone=21,11 fast_pskip=1 ch
roma_qp_offset=-2 threads=6 lookahead_threads=1 sliced_threads=0 nr=0 decimate=1 interlaced=0 bluray_compat=0 constrained_intra=0 bframes=8 b_pyramid=2 b_adapt=
2 b_bias=0 direct=3 weightb=1 open_gop=0 weightp=2 keyint=250 keyint_min=25 scenecut=40 intra_refresh=0 rc_lookahead=60 rc=crf mbtree=1 crf=23.0 qcomp=0.60 qpmi
n=0 qpmax=69 qpstep=4 ip_ratio=1.40 aq=1:1.00
Output #0, mp4, to 'output.default.mp4':
  Metadata:
    encoder         : Lavf56.4.101
    Stream #0:0: Video: h264 (libx264) ([33][0][0][0] / 0x0021), yuv420p, 640x360 [SAR 1:1 DAR 16:9], q=-1--1, 25 fps, 12800 tbn, 25 tbc
    Metadata:
      encoder         : Lavc56.1.100 libx264
    Stream #0:1: Audio: aac (libvo_aacenc) ([64][0][0][0] / 0x0040), 48000 Hz, stereo, s16, 128 kb/s
    Metadata:
      encoder         : Lavc56.1.100 libvo_aacenc
Stream mapping:
  Stream #0:0 -> #0:0 (mpeg4 (native) -> h264 (libx264))
  Stream #0:1 -> #0:1 (pcm_s16le (native) -> aac (libvo_aacenc))
Press [q] to stop, [?] for help
frame=  251 fps= 15 q=-1.0 Lsize=    1184kB time=00:00:10.01 bitrate= 968.6kbits/s dup=1 drop=0
video:1019kB audio:157kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 0.723548%
[libx264 @ 0364f380] frame I:2     Avg QP:25.09  size: 36162
[libx264 @ 0364f380] frame P:60    Avg QP:24.47  size: 12750
[libx264 @ 0364f380] frame B:189   Avg QP:31.31  size:  1085
[libx264 @ 0364f380] consecutive B-frames:  0.8%  6.4% 12.0% 33.5% 13.9% 33.5%  0.0%  0.0%  0.0%
[libx264 @ 0364f380] mb I  I16..4:  4.0% 77.1% 18.9%
[libx264 @ 0364f380] mb P  I16..4:  0.4%  1.3%  0.4%  P16..4: 36.6% 20.6% 30.7%  3.7%  1.5%    skip: 4.8%
[libx264 @ 0364f380] mb B  I16..4:  0.0%  0.0%  0.0%  B16..8: 47.7%  4.8%  1.7%  direct: 1.3%  skip:44.4%  L0:41.8% L1:40.5% BI:17.7%
[libx264 @ 0364f380] 8x8 transform intra:70.9% inter:53.0%
[libx264 @ 0364f380] direct mvs  spatial:97.4% temporal:2.6%
[libx264 @ 0364f380] coded y,uvDC,uvAC intra: 81.8% 78.8% 40.8% inter: 14.5% 11.3% 2.0%
[libx264 @ 0364f380] i16 v,h,dc,p: 41% 17% 28% 14%
[libx264 @ 0364f380] i8 v,h,dc,ddl,ddr,vr,hd,vl,hu: 15% 10% 18%  8% 10% 10%  9%  9% 11%
[libx264 @ 0364f380] i4 v,h,dc,ddl,ddr,vr,hd,vl,hu: 16%  6%  6% 10% 13% 13% 12% 12% 13%
[libx264 @ 0364f380] i8c dc,h,v,p: 28% 28% 31% 13%
[libx264 @ 0364f380] Weighted P-Frames: Y:18.3% UV:10.0%
[libx264 @ 0364f380] ref P L0: 58.5% 17.3%  8.4%  4.3%  1.8%  2.6%  1.3%  1.3%  0.7%  0.9%  0.5%  0.5%  0.5%  0.5%  0.4%  0.5%
[libx264 @ 0364f380] ref B L0: 91.8%  3.9%  2.0%  0.5%  0.5%  0.3%  0.2%  0.1%  0.2%  0.1%  0.1%  0.1%  0.1%  0.1%  0.0%
[libx264 @ 0364f380] ref B L1: 95.5%  4.5%
[libx264 @ 0364f380] kb/s:830.51

Expected default refs value: 16
Actual refs value:           16

Documented '-x264opts level=x.y' option:

ffmpeg -i _640.360.25.avi -preset veryslow -x264opts level=3.0 output.--level3.0.mp4
ffmpeg version N-66232-g5e3da25 Copyright (c) 2000-2014 the FFmpeg developers
  built on Sep 10 2014 22:01:59 with gcc 4.8.3 (GCC)
  configuration: --enable-gpl --enable-version3 --disable-w32threads --enable-avisynth --enable-bzlib --enable-fontconfig --enable-frei0r --enable-gnutls --enab
le-iconv --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libfreetype --enable-libgme --enable-libgsm --enable-libilbc --enable-lib
modplug --enable-libmp3lame --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libopus --enable-librtmp --enable-libschroedinge
r --enable-libsoxr --enable-libspeex --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvo-aacenc --enable-libvo-amrwbenc --enable-libvorbis
 --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxavs --enable-libxvid --enable-decklink --enable-zlib
  libavutil      54.  7.100 / 54.  7.100
  libavcodec     56.  1.100 / 56.  1.100
  libavformat    56.  4.101 / 56.  4.101
  libavdevice    56.  0.100 / 56.  0.100
  libavfilter     5.  1.100 /  5.  1.100
  libswscale      3.  0.100 /  3.  0.100
  libswresample   1.  1.100 /  1.  1.100
  libpostproc    53.  0.100 / 53.  0.100
Guessed Channel Layout for  Input Stream #0.1 : stereo
Input #0, avi, from '_640.360.25.avi':
  Duration: 00:00:10.00, start: 0.000000, bitrate: 7561 kb/s
    Stream #0:0: Video: mpeg4 (Advanced Simple Profile) (XVID / 0x44495658), yuv420p, 640x360 [SAR 1:1 DAR 16:9], 6031 kb/s, 25 fps, 25 tbr, 25 tbn, 25 tbc
    Stream #0:1: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 48000 Hz, 2 channels, s16, 1536 kb/s
[libx264 @ 0429e880] using SAR=1/1
[libx264 @ 0429e880] DPB size (16 frames, 14720 mbs) > level limit (8 frames, 8100 mbs)
[libx264 @ 0429e880] using cpu capabilities: MMX2 SSE2Fast SSSE3 SSE4.2 AVX
[libx264 @ 0429e880] profile High, level 3.0
[libx264 @ 0429e880] 264 - core 142 r2479 dd79a61 - H.264/MPEG-4 AVC codec - Copyleft 2003-2014 - http://www.videolan.org/x264.html - options: cabac=1 ref=16 de
block=1:0:0 analyse=0x3:0x133 me=umh subme=10 psy=1 psy_rd=1.00:0.00 mixed_ref=1 me_range=24 chroma_me=1 trellis=2 8x8dct=1 cqm=0 deadzone=21,11 fast_pskip=1 ch
roma_qp_offset=-2 threads=6 lookahead_threads=1 sliced_threads=0 nr=0 decimate=1 interlaced=0 bluray_compat=0 constrained_intra=0 bframes=8 b_pyramid=2 b_adapt=
2 b_bias=0 direct=3 weightb=1 open_gop=0 weightp=2 keyint=250 keyint_min=25 scenecut=40 intra_refresh=0 rc_lookahead=60 rc=crf mbtree=1 crf=23.0 qcomp=0.60 qpmi
n=0 qpmax=69 qpstep=4 ip_ratio=1.40 aq=1:1.00
Output #0, mp4, to 'output.--level3.0.mp4':
  Metadata:
    encoder         : Lavf56.4.101
    Stream #0:0: Video: h264 (libx264) ([33][0][0][0] / 0x0021), yuv420p, 640x360 [SAR 1:1 DAR 16:9], q=-1--1, 25 fps, 12800 tbn, 25 tbc
    Metadata:
      encoder         : Lavc56.1.100 libx264
    Stream #0:1: Audio: aac (libvo_aacenc) ([64][0][0][0] / 0x0040), 48000 Hz, stereo, s16, 128 kb/s
    Metadata:
      encoder         : Lavc56.1.100 libvo_aacenc
Stream mapping:
  Stream #0:0 -> #0:0 (mpeg4 (native) -> h264 (libx264))
  Stream #0:1 -> #0:1 (pcm_s16le (native) -> aac (libvo_aacenc))
Press [q] to stop, [?] for help
frame=  251 fps= 15 q=-1.0 Lsize=    1184kB time=00:00:10.01 bitrate= 968.7kbits/s dup=1 drop=0
video:1019kB audio:157kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 0.723486%
[libx264 @ 0429e880] frame I:2     Avg QP:25.09  size: 36162
[libx264 @ 0429e880] frame P:60    Avg QP:24.47  size: 12748
[libx264 @ 0429e880] frame B:189   Avg QP:31.30  size:  1085
[libx264 @ 0429e880] consecutive B-frames:  0.8%  6.4% 12.0% 33.5% 13.9% 33.5%  0.0%  0.0%  0.0%
[libx264 @ 0429e880] mb I  I16..4:  4.0% 77.1% 18.9%
[libx264 @ 0429e880] mb P  I16..4:  0.4%  1.3%  0.4%  P16..4: 36.6% 20.6% 30.7%  3.7%  1.5%    skip: 4.9%
[libx264 @ 0429e880] mb B  I16..4:  0.0%  0.0%  0.0%  B16..8: 47.7%  4.8%  1.7%  direct: 1.3%  skip:44.4%  L0:41.8% L1:40.5% BI:17.7%
[libx264 @ 0429e880] 8x8 transform intra:70.9% inter:53.0%
[libx264 @ 0429e880] direct mvs  spatial:97.4% temporal:2.6%
[libx264 @ 0429e880] coded y,uvDC,uvAC intra: 81.8% 78.9% 40.8% inter: 14.5% 11.3% 2.0%
[libx264 @ 0429e880] i16 v,h,dc,p: 41% 17% 28% 14%
[libx264 @ 0429e880] i8 v,h,dc,ddl,ddr,vr,hd,vl,hu: 15% 10% 18%  8% 10% 10%  9%  9% 11%
[libx264 @ 0429e880] i4 v,h,dc,ddl,ddr,vr,hd,vl,hu: 15%  6%  6% 10% 13% 12% 12% 12% 13%
[libx264 @ 0429e880] i8c dc,h,v,p: 28% 28% 31% 13%
[libx264 @ 0429e880] Weighted P-Frames: Y:18.3% UV:10.0%
[libx264 @ 0429e880] ref P L0: 58.5% 17.3%  8.4%  4.3%  1.8%  2.6%  1.3%  1.3%  0.7%  0.9%  0.5%  0.6%  0.5%  0.5%  0.4%  0.5%
[libx264 @ 0429e880] ref B L0: 91.8%  3.9%  2.0%  0.6%  0.5%  0.3%  0.2%  0.1%  0.2%  0.1%  0.1%  0.1%  0.1%  0.1%  0.0%
[libx264 @ 0429e880] ref B L1: 95.5%  4.5%
[libx264 @ 0429e880] kb/s:830.59

Expected refs value:  8
Actual refs value:   16

Undocumented '-level x.y' option:

ffmpeg -i _640.360.25.avi -preset veryslow -level 3.0 output.-level3.0.mp4
ffmpeg version N-66232-g5e3da25 Copyright (c) 2000-2014 the FFmpeg developers
  built on Sep 10 2014 22:01:59 with gcc 4.8.3 (GCC)
  configuration: --enable-gpl --enable-version3 --disable-w32threads --enable-avisynth --enable-bzlib --enable-fontconfig --enable-frei0r --enable-gnutls --enab
le-iconv --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libfreetype --enable-libgme --enable-libgsm --enable-libilbc --enable-lib
modplug --enable-libmp3lame --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libopus --enable-librtmp --enable-libschroedinge
r --enable-libsoxr --enable-libspeex --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvo-aacenc --enable-libvo-amrwbenc --enable-libvorbis
 --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxavs --enable-libxvid --enable-decklink --enable-zlib
  libavutil      54.  7.100 / 54.  7.100
  libavcodec     56.  1.100 / 56.  1.100
  libavformat    56.  4.101 / 56.  4.101
  libavdevice    56.  0.100 / 56.  0.100
  libavfilter     5.  1.100 /  5.  1.100
  libswscale      3.  0.100 /  3.  0.100
  libswresample   1.  1.100 /  1.  1.100
  libpostproc    53.  0.100 / 53.  0.100
Guessed Channel Layout for  Input Stream #0.1 : stereo
Input #0, avi, from '_640.360.25.avi':
  Duration: 00:00:10.00, start: 0.000000, bitrate: 7561 kb/s
    Stream #0:0: Video: mpeg4 (Advanced Simple Profile) (XVID / 0x44495658), yuv420p, 640x360 [SAR 1:1 DAR 16:9], 6031 kb/s, 25 fps, 25 tbr, 25 tbn, 25 tbc
    Stream #0:1: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 48000 Hz, 2 channels, s16, 1536 kb/s
[libx264 @ 041af7e0] using SAR=1/1
[libx264 @ 041af7e0] using cpu capabilities: MMX2 SSE2Fast SSSE3 SSE4.2 AVX
[libx264 @ 041af7e0] profile High, level 3.0
[libx264 @ 041af7e0] 264 - core 142 r2479 dd79a61 - H.264/MPEG-4 AVC codec - Copyleft 2003-2014 - http://www.videolan.org/x264.html - options: cabac=1 ref=8 deb
lock=1:0:0 analyse=0x3:0x133 me=umh subme=10 psy=1 psy_rd=1.00:0.00 mixed_ref=1 me_range=24 chroma_me=1 trellis=2 8x8dct=1 cqm=0 deadzone=21,11 fast_pskip=1 chr
oma_qp_offset=-2 threads=6 lookahead_threads=1 sliced_threads=0 nr=0 decimate=1 interlaced=0 bluray_compat=0 constrained_intra=0 bframes=8 b_pyramid=2 b_adapt=2
 b_bias=0 direct=3 weightb=1 open_gop=0 weightp=2 keyint=250 keyint_min=25 scenecut=40 intra_refresh=0 rc_lookahead=60 rc=crf mbtree=1 crf=23.0 qcomp=0.60 qpmin
=0 qpmax=69 qpstep=4 ip_ratio=1.40 aq=1:1.00
Output #0, mp4, to 'output.-level3.0.mp4':
  Metadata:
    encoder         : Lavf56.4.101
    Stream #0:0: Video: h264 (libx264) ([33][0][0][0] / 0x0021), yuv420p, 640x360 [SAR 1:1 DAR 16:9], q=-1--1, 25 fps, 12800 tbn, 25 tbc
    Metadata:
      encoder         : Lavc56.1.100 libx264
    Stream #0:1: Audio: aac (libvo_aacenc) ([64][0][0][0] / 0x0040), 48000 Hz, stereo, s16, 128 kb/s
    Metadata:
      encoder         : Lavc56.1.100 libvo_aacenc
Stream mapping:
  Stream #0:0 -> #0:0 (mpeg4 (native) -> h264 (libx264))
  Stream #0:1 -> #0:1 (pcm_s16le (native) -> aac (libvo_aacenc))
Press [q] to stop, [?] for help
frame=  251 fps= 20 q=-1.0 Lsize=    1189kB time=00:00:10.01 bitrate= 972.8kbits/s dup=1 drop=0
video:1024kB audio:157kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 0.720318%
[libx264 @ 041af7e0] frame I:2     Avg QP:25.09  size: 36162
[libx264 @ 041af7e0] frame P:60    Avg QP:24.47  size: 12846
[libx264 @ 041af7e0] frame B:189   Avg QP:31.33  size:  1082
[libx264 @ 041af7e0] consecutive B-frames:  0.8%  6.4% 12.0% 33.5% 13.9% 33.5%  0.0%  0.0%  0.0%
[libx264 @ 041af7e0] mb I  I16..4:  4.0% 77.1% 18.9%
[libx264 @ 041af7e0] mb P  I16..4:  0.5%  1.2%  0.4%  P16..4: 36.3% 20.6% 30.8%  3.8%  1.6%    skip: 4.8%
[libx264 @ 041af7e0] mb B  I16..4:  0.0%  0.1%  0.0%  B16..8: 48.1%  4.7%  1.5%  direct: 1.3%  skip:44.3%  L0:41.3% L1:40.7% BI:18.0%
[libx264 @ 041af7e0] 8x8 transform intra:68.7% inter:52.3%
[libx264 @ 041af7e0] direct mvs  spatial:97.4% temporal:2.6%
[libx264 @ 041af7e0] coded y,uvDC,uvAC intra: 80.8% 78.4% 39.7% inter: 14.6% 11.3% 2.0%
[libx264 @ 041af7e0] i16 v,h,dc,p: 43% 17% 25% 15%
[libx264 @ 041af7e0] i8 v,h,dc,ddl,ddr,vr,hd,vl,hu: 15% 10% 18%  8% 10% 10% 10%  9% 11%
[libx264 @ 041af7e0] i4 v,h,dc,ddl,ddr,vr,hd,vl,hu: 16%  6%  6% 10% 12% 13% 11% 12% 13%
[libx264 @ 041af7e0] i8c dc,h,v,p: 29% 27% 31% 14%
[libx264 @ 041af7e0] Weighted P-Frames: Y:18.3% UV:10.0%
[libx264 @ 041af7e0] ref P L0: 59.9% 17.9%  8.6%  4.8%  2.1%  3.1%  1.5%  1.9%  0.2%  0.0%
[libx264 @ 041af7e0] ref B L0: 92.3%  4.0%  2.1%  0.5%  0.6%  0.3%  0.1%
[libx264 @ 041af7e0] ref B L1: 95.5%  4.5%
[libx264 @ 041af7e0] kb/s:834.70

Expected refs value: 8
Actual refs value:   8

Arguably the most consistent fix would be to correct '-x264opts level=x.y' to behave like '-level x.y', and for '-level x.y' to also be documented.

[Timothy Gu]

To adjust level through -x264opts, we will have to make a special case as x264 requires some further configuration else than just setting the level in the context. Or it could be fixed on the x264 side.

On the other hand, -level documentation should be fixed.

[Francois Visagie]

H.264 level- and maxref calculator

[Francois Visagie]

Replying to Timothy_Gu:

To adjust level through -x264opts, we will have to make a special case as x264 requires some further configuration else than just setting the level in the context. Or it could be fixed on the x264 side.

Since '-level x.y' seems to correctly set that configuration - including refs - is there the possibility that the handling of '-x264opts level=x.y' could be directed to that of '-level x.y'?

In any case, while I'm not able to analyse the code, for three reasons there does seem to be the possibility that the further configuration is correctly set by '-x264opts level', but (accidentally) partially overwritten by ffmpeg. 1) 'x264 --level' correctly sets the level-specific configuration, including refs, which creates the possibility that libx264 might do the same. 2) When not given a '-refs' value, ffmpeg always defaults to 16. 3) All encodes done with '-x264opts level' and without '-refs' have refs=16. Together these give rise to the possibility that when '-x264opts level' is used, libx264 correctly sets the configuration, but that ffmpeg overwrites refs with its default of 16.

If that is the case, ffmpeg's logic could be changed to not pass a refs value to libx264 when either of '-level' or '-x264opts level' is used, and no '-refs' value is provided.

If that is not the case but ffmpeg somehow needs to anticipate the level and/or level-specific maxrefs level libx264 will need, you could refer to the calculations in attachment ​http://trac.ffmpeg.org/attachment/ticket/3947/h264levl.bat.

On the other hand, -level documentation should be fixed.

Please. At the moment it only says

level integer (encoding,audio,video)

    Possible values:

    ‘unknown’

Apart from missing possible values etc., it should mention whether this option takes into account x264's handling of refs wrt. bframes and b-pyramid ​http://forum.doom9.org/showthread.php?t=142758.

[Carl Eugen Hoyos]

Isn't this just a documentation issue?

[Francois Visagie]

In my view it is at least a documentation issue which I would appreciate fixed. If any of the ffmpeg developers see fit to also improve behaviour around maxrefs management, that is their prerogative.

For updating documentation, may I request that it also address whether this option takes into account x264's handling of refs wrt. bframes and b-pyramid [​​http://forum.doom9.org/showthread.php?t=142758]?

[Francois Visagie]

Unfortunately I can confirm that there is also a software bug, in addition to a documentation error. Let's restate the information from ​comment 2:

1. When '-x264opts level=x.y' is used, ffmpeg does not correctly set reference frames for the specified level (shown in original report above).
2. However, when --level is used with x264, it DOES correctly set reference frames for the specified level:

C:\Users\fvisagie\Videos\Home Videos\Testing\x264>h264levl 720 576 25 1500000

h264levl v1.1 (c) F. Visagie 2014/10/31

level=3
maxref=5
x264maxref=5

C:\Users\fvisagie\Videos\Home Videos\Testing\x264>x264 --preset veryslow --bitrate 1500 --level 3 -o zzz.m4v inprogressive.mpg
[mpeg @ 003e29c0] max_analyze_duration 5000000 reached
lavf [info]: 720x576p 64:45 @ 25/1 fps (vfr)
x264 [info]: using SAR=64/45
x264 [info]: using cpu capabilities: MMX2 SSE2Fast SSSE3 SSE4.2 AVX
x264 [info]: profile High, level 3.0
x264 [info]: frame I:15    Avg QP:25.41  size: 45805
x264 [info]: frame P:473   Avg QP:30.64  size: 12431
x264 [info]: frame B:1012  Avg QP:34.26  size:  4176
x264 [info]: consecutive B-frames:  3.9%  4.1% 64.0%  4.5%  5.0% 18.4%  0.0%  0.0%  0.0%
x264 [info]: mb I  I16..4:  3.6% 87.1%  9.3%
x264 [info]: mb P  I16..4:  3.2% 19.9%  1.6%  P16..4: 41.2% 15.1%  8.9%  0.2%  0.0%    skip: 9.9%
x264 [info]: mb B  I16..4:  0.6%  3.0%  0.2%  B16..8: 42.4% 10.0%  2.0%  direct: 3.1%  skip:38.8%  L0:38.0% L1:51.3% BI:10.7%
x264 [info]: final ratefactor: 25.75
x264 [info]: 8x8 transform intra:81.2% inter:82.2%
x264 [info]: direct mvs  spatial:99.6% temporal:0.4%
x264 [info]: coded y,uvDC,uvAC intra: 69.5% 64.3% 22.2% inter: 19.9% 13.5% 1.2%
x264 [info]: i16 v,h,dc,p: 29% 26%  8% 36%
x264 [info]: i8 v,h,dc,ddl,ddr,vr,hd,vl,hu: 16% 10%  5%  7% 11% 15% 12% 12% 12%
x264 [info]: i4 v,h,dc,ddl,ddr,vr,hd,vl,hu: 22% 10%  4%  7% 12% 16% 11% 10%  9%
x264 [info]: i8c dc,h,v,p: 34% 24% 23% 19%
x264 [info]: Weighted P-Frames: Y:1.1% UV:0.4%
x264 [info]: ref P L0: 58.5% 20.4% 12.8%  3.2%  3.0%  2.0%  0.1%
x264 [info]: ref B L0: 90.1%  6.9%  2.2%  0.8%
x264 [info]: ref B L1: 96.2%  3.8%
x264 [info]: kb/s:1441.07

encoded 1500 frames, 11.38 fps, 1441.07 kb/s

Unfortunately I do not know how to show encoder settings or number of reference frames in the output file with ffprobe.
MediaInfo output:

General
Complete name                            : C:\Users\fvisagie\Videos\Home Videos\Testing\x264\zzz.m4v
Format                                   : AVC
Format/Info                              : Advanced Video Codec
File size                                : 10.3 MiB

Video
Format                                   : AVC
Format/Info                              : Advanced Video Codec
Format profile                           : High@L3.0
Format settings, CABAC                   : Yes
Format settings, ReFrames                : 5 frames
Bit rate                                 : 1 500 Kbps
Width                                    : 720 pixels
Height                                   : 576 pixels
Display aspect ratio                     : 16:9
Frame rate mode                          : Variable
Standard                                 : PAL
Color space                              : YUV
Chroma subsampling                       : 4:2:0
Bit depth                                : 8 bits
Scan type                                : Progressive
Writing library                          : x264 core 142 r2479 dd79a61
Encoding settings                        : cabac=1 / ref=5 / deblock=1:0:0 / analyse=0x3:0x133 / me=umh / subme=10 / psy=1 / psy_rd=1.00:0.00 / mixed_ref=1 / me_range=24 / chroma_me=1 / trellis=2 / 8x8dct=1 / cqm=0 / deadzone=21,11 / fast_pskip=1 / chroma_qp_offset=-2 / threads=6 / lookahead_threads=1 / sliced_threads=0 / nr=0 / decimate=1 / interlaced=0 / bluray_compat=0 / constrained_intra=0 / bframes=8 / b_pyramid=2 / b_adapt=2 / b_bias=0 / direct=3 / weightb=1 / open_gop=0 / weightp=2 / keyint=250 / keyint_min=25 / scenecut=40 / intra_refresh=0 / rc_lookahead=60 / rc=abr / mbtree=1 / bitrate=1500 / ratetol=1.0 / qcomp=0.60 / qpmin=0 / qpmax=69 / qpstep=4 / ip_ratio=1.40 / aq=1:1.00

[Francois Visagie]

Replying to cehoyos:
Can you explain how - given that comment 1 indicated this in addition to being a documentation issue also to be a code issue related to avcodec, and that comment 6 confirmed that - you believe this solely to be a documentation issue?

[Stefano Sabatini]

This should be fixed in commit:

commit d0f071dfe743a410ff385c832b9c3ff47fd73c94
Author: Stefano Sabatini <stefasab@gmail.com>
Date:   Sat Aug 26 02:53:28 2023 +0200

    doc/encoders/libx264: clarify meaning of level option
    
    In particular, clarify that it can either be set as a field of
    AVCodecContext or as an x264 option, using a different specification.
    
    Should address trac issue:
    http://trac.ffmpeg.org/ticket/3947