v4l2-ctlで行うUSBカメラ設定方法まとめ

v4l2-ctlはv4l2-utils(Video4Linux utils)に含まれるカメラの詳細設定ツールです。色々なことができるので主な使い方を纏めておきます。ちなみに実験用に使用したUSBカメラは『LOGICOOL HD WebCam C525』です。

1. インストール

v4l2-ctlを使用するには、v4l-utilsをインストールします。

// 接続されているカメラの情報を取得する為にv4l-utilsをインストール
// (既にインストール済みかも)
$ sudo apt install v4l-utils

2. 接続しているUSBカメラの全情報を出力するには

$ v4l2-ctl --all

// 接続しているUSBカメラの全情報出力
$ v4l2-ctl --all
Driver Info:
	Driver name      : uvcvideo
	Card type        : HD Webcam C525
	Bus info         : usb-0000:01:00.0-1.1
	Driver version   : 5.10.17
	Capabilities     : 0x84a00001
		Video Capture
		Metadata Capture
		Streaming
		Extended Pix Format
		Device Capabilities
	Device Caps      : 0x04200001
		Video Capture
		Streaming
		Extended Pix Format
Media Driver Info:
	Driver name      : uvcvideo
	Model            : HD Webcam C525
	Serial           : 7928C640
	Bus info         : usb-0000:01:00.0-1.1
	Media version    : 5.10.17
	Hardware revision: 0x00000010 (16)
	Driver version   : 5.10.17
Interface Info:
	ID               : 0x03000002
	Type             : V4L Video
Entity Info:
	ID               : 0x00000001 (1)
	Name             : HD Webcam C525
	Function         : V4L2 I/O
	Flags         : default
	Pad 0x01000007   : 0: Sink
	  Link 0x02000019: from remote pad 0x100000a of entity 'Extension 5': Data, Enabled, Immutable
Priority: 2
Video input : 0 (Camera 1: ok)
Format Video Capture:
	Width/Height      : 640/480
	Pixel Format      : 'YUYV' (YUYV 4:2:2)
	Field             : None
	Bytes per Line    : 1280
	Size Image        : 614400
	Colorspace        : sRGB
	Transfer Function : Rec. 709
	YCbCr/HSV Encoding: ITU-R 601
	Quantization      : Default (maps to Limited Range)
	Flags             : 
Crop Capability Video Capture:
	Bounds      : Left 0, Top 0, Width 640, Height 480
	Default     : Left 0, Top 0, Width 640, Height 480
	Pixel Aspect: 1/1
Selection: crop_default, Left 0, Top 0, Width 640, Height 480, Flags: 
Selection: crop_bounds, Left 0, Top 0, Width 640, Height 480, Flags: 
Streaming Parameters Video Capture:
	Capabilities     : timeperframe
	Frames per second: 30.000 (30/1)
	Read buffers     : 0
                     brightness 0x00980900 (int)    : min=0 max=255 step=1 default=128 value=128
                       contrast 0x00980901 (int)    : min=0 max=255 step=1 default=32 value=32
                     saturation 0x00980902 (int)    : min=0 max=255 step=1 default=32 value=32
 white_balance_temperature_auto 0x0098090c (bool)   : default=1 value=1
                           gain 0x00980913 (int)    : min=0 max=255 step=1 default=64 value=64
           power_line_frequency 0x00980918 (menu)   : min=0 max=2 default=2 value=2
      white_balance_temperature 0x0098091a (int)    : min=2800 max=6500 step=1 default=5500 value=5500 flags=inactive
                      sharpness 0x0098091b (int)    : min=0 max=255 step=1 default=22 value=22
         backlight_compensation 0x0098091c (int)    : min=0 max=1 step=1 default=1 value=1
                  exposure_auto 0x009a0901 (menu)   : min=0 max=3 default=3 value=3
              exposure_absolute 0x009a0902 (int)    : min=3 max=2047 step=1 default=166 value=166 flags=inactive
         exposure_auto_priority 0x009a0903 (bool)   : default=0 value=1
                   pan_absolute 0x009a0908 (int)    : min=-36000 max=36000 step=3600 default=0 value=0
                  tilt_absolute 0x009a0909 (int)    : min=-36000 max=36000 step=3600 default=0 value=0
                 focus_absolute 0x009a090a (int)    : min=0 max=255 step=5 default=60 value=60 flags=inactive
                     focus_auto 0x009a090c (bool)   : default=1 value=1
                  zoom_absolute 0x009a090d (int)    : min=1 max=5 step=1 default=1 value=1
                      led1_mode 0x0a046d05 (menu)   : min=0 max=3 default=0 value=3
                 led1_frequency 0x0a046d06 (int)    : min=0 max=255 step=1 default=0 value=0

3. USBカメラが対応している設定項目一覧を確認するには

$ v4l2-ctl -L

$ v4l2-ctl -L
                     brightness 0x00980900 (int)    : min=0 max=255 step=1 default=128 value=128
                       contrast 0x00980901 (int)    : min=0 max=255 step=1 default=32 value=32
                     saturation 0x00980902 (int)    : min=0 max=255 step=1 default=32 value=32
 white_balance_temperature_auto 0x0098090c (bool)   : default=1 value=0
                           gain 0x00980913 (int)    : min=0 max=255 step=1 default=64 value=64
           power_line_frequency 0x00980918 (menu)   : min=0 max=2 default=2 value=2
				0: Disabled
				1: 50 Hz
				2: 60 Hz
      white_balance_temperature 0x0098091a (int)    : min=2800 max=6500 step=1 default=5500 value=5500
                      sharpness 0x0098091b (int)    : min=0 max=255 step=1 default=22 value=22
         backlight_compensation 0x0098091c (int)    : min=0 max=1 step=1 default=1 value=1
                  exposure_auto 0x009a0901 (menu)   : min=0 max=3 default=3 value=3
				1: Manual Mode
				3: Aperture Priority Mode
              exposure_absolute 0x009a0902 (int)    : min=3 max=2047 step=1 default=166 value=166 flags=inactive
         exposure_auto_priority 0x009a0903 (bool)   : default=0 value=1
                   pan_absolute 0x009a0908 (int)    : min=-36000 max=36000 step=3600 default=0 value=0
                  tilt_absolute 0x009a0909 (int)    : min=-36000 max=36000 step=3600 default=0 value=0
                 focus_absolute 0x009a090a (int)    : min=0 max=255 step=5 default=60 value=60 flags=inactive
                     focus_auto 0x009a090c (bool)   : default=1 value=1
                  zoom_absolute 0x009a090d (int)    : min=1 max=5 step=1 default=1 value=1
                      led1_mode 0x0a046d05 (menu)   : min=0 max=3 default=0 value=3
				0: Off
				1: On
				2: Blink
				3: Auto
                 led1_frequency 0x0a046d06 (int)    : min=0 max=255 step=1 default=0 value=0

4. カメラ設定(ホワイトバランス等)を確認・変更するには

設定の確認は以下で行います。

$ v4l2-ctl -C <設定項目名>

設定は以下で行います。

$ v4l2-ctl -c <設定項目名>=値

設定項目名と値は以下で確認できます。

$ v4l2-ctl -L

USBカメラと設定によりますが、露光モードを手動に変えないと変更できない設定等があります。

// 露光モード確認
$ v4l2-ctl -C exposure_auto
exposure_auto: 3

// 露光モードを手動モードに設定(1:手動  3:絞り優先モード)
$ v4l2-ctl -c exposure_auto=1

// 露光モードが設定できたか念の為確認
$ v4l2-ctl -C exposure_auto
exposure_auto: 1

私のUSBカメラで可能な限り設定を変更してみました。

// 輝度を取得する
$ v4l2-ctl -C brightness
brightness: 128
// 輝度を設定する
$ v4l2-ctl -c brightness=255
// デバイスを指定して輝度を設定する(デバイス /dev/video0 指定)
$ v4l2-ctl -d /dev/video0 -c brightness=255


// コントラストを取得する
$ v4l2-ctl -C contrast
contrast: 32
// コントラストを設定する
$ v4l2-ctl -c contrast=123
// コントラストと輝度を設定する
$ v4l2-ctl -c contrast=20 -c brightness=100
// コントラストと輝度を確認する
$ v4l2-ctl -C contrast -C brightness
contrast: 20
brightness: 100


// 彩度を取得する
$ v4l2-ctl -C saturation
saturation: 32
// 彩度を設定する
$ v4l2-ctl -c saturation=90


// 自動ホワイトバランス機能を使用するかどうかを取得する
$ v4l2-ctl -C white_balance_temperature_auto
white_balance_temperature_auto: 1
// 自動ホワイトバランス機能を無効に設定する(1:有効  0:無効)
$ v4l2-ctl -c white_balance_temperature_auto=0


// ゲインを取得する
$ v4l2-ctl -C gain
gain: 43
// ゲインを設定する
$ v4l2-ctl -c gain=100


// フリッカー(ちらつき)対策用の電源周波数設定を取得する(0:無効 1:50Hz 2:60Hz)
$ v4l2-ctl -C power_line_frequency
power_line_frequency: 2
// フリッカー(ちらつき)対策用の電源周波数設定を取得する(0:無効 1:50Hz 2:60Hz)
$ v4l2-ctl -c power_line_frequency=1


// ホワイトバランスを取得する
$ v4l2-ctl -C white_balance_temperature
gain: 43
// ホワイトバランスを設定する
// white_balance_temperature_auto=0 で
// 先に自動ホワイトバランスをOFFにしておく必要がある
$ v4l2-ctl -c white_balance_temperature_auto=0
$ v4l2-ctl -c white_balance_temperature=3000


// シャープネスを取得する
$ v4l2-ctl -C sharpness
sharpness: 22
// シャープネスを設定する
$ v4l2-ctl -c sharpness=200


// バックライト補正を取得する(1:有効 0:無効)
$ v4l2-ctl -C backlight_compensation
backlight_compensation: 1
// バックライト補正を設定する(1:有効 0:無効)
$ v4l2-ctl -c backlight_compensation=0


// 露光時間を取得する
$ v4l2-ctl -C exposure_absolute
exposure_absolute: 249
// 露光時間を設定する(単位ms: 例:2000ms=2秒)
// 事前に露光モードを手動に設定しておく必要がある。
$ v4l2-ctl -c exposure_auto=1
$ v4l2-ctl -c exposure_absolute=2000


// 自動露出優先制御を取得する(1:自動 0:手動)
$ v4l2-ctl -C exposure_auto_priority
exposure_auto_priority: 1
// 自動露出優先制御を設定する(1:自動 0:手動)
// 事前に自動露出モードを手動以外(絞り優先等)にしておく
$ v4l2-ctl -c exposure_auto=3
$ v4l2-ctl -c exposure_auto_priority=0
// (このモードの使い方はよく分かっていない)


// 以下は割愛
// pan_absolute : カメラを水平方向に回転させる
// tilt_absolute : カメラを垂直方向に回転させる
// focus_absolute : フォーカス位置を変更する
// focus_auto : 自動フォーカスモードを有効/無効にする
// zoom_absolute : ズーム設定
// led1_mode : led設定。光らせることができる。
// led1_frequency : led設定。点滅速度。

5. 対応解像度一覧を表示するには

$ v4l2-ctl --list-formats-ext

// 解像度一覧を表示
$ v4l2-ctl --list-formats-ext

6. フレームレートを設定するには

// フレームレート設定
$ v4l2-ctl -p 30
Frame rate set to 30.000 fps

// フレームレートを確認
$ v4l2-ctl -P
Streaming Parameters Video Capture:
	Capabilities     : timeperframe
	Frames per second: 30.000 (30/1)
	Read buffers     : 0

7. ビデオキャプチャー設定を変更するには

// まずはビデオキャプチャー設定を確認
$ v4l2-ctl -V
Format Video Capture:
	Width/Height      : 640/480
	Pixel Format      : 'YUYV' (YUYV 4:2:2)
	Field             : None
	Bytes per Line    : 1280
	Size Image        : 614400
	Colorspace        : sRGB
	Transfer Function : Rec. 709
	YCbCr/HSV Encoding: ITU-R 601
	Quantization      : Default (maps to Limited Range)

// ビデオキャプチャー設定を変更
// 今回は解像度とフォーマットのみを変更。
$ v4l2-ctl -v width=1280,height=720,pixelformat=YUYV

// 以下で更に詳細設定が可能
// -v width=<w>,height=<h>,pixelformat=<pf>,field=<f>,colorspace=<c>,
//                   xfer=<xf>,ycbcr=<y>,hsv=<hsv>,quantization=<q>,
//                   premul-alpha,bytesperline=<bpl>
//                      set/try the video capture format [VIDIOC_S/TRY_FMT]
//                      pixelformat is either the format index as reported by
//                        --list-formats, or the fourcc value as a string.
//                      The bytesperline option can be used multiple times, once for each plane.
//                      premul-alpha sets V4L2_PIX_FMT_FLAG_PREMUL_ALPHA.
//                      <f> can be one of the following field layouts:
//                        any, none, top, bottom, interlaced, seq_tb, seq_bt,
//                        alternate, interlaced_tb, interlaced_bt
//                      <c> can be one of the following colorspaces:
//                        smpte170m, smpte240m, rec709, 470m, 470bg, jpeg, srgb,
//                        oprgb, bt2020, dcip3
//                      <xf> can be one of the following transfer functions:
//                        default, 709, srgb, oprgb, smpte240m, smpte2084, dcip3, none
//                      <y> can be one of the following Y'CbCr encodings:
//                        default, 601, 709, xv601, xv709, bt2020, bt2020c, smpte240m
//                      <hsv> can be one of the following HSV encodings:
//                        default, 180, 256
//                      <q> can be one of the following quantization methods:
//                        default, full-range, lim-range

8. 動画を録画するには

// ファイル名『testrec.raw』で録画を開始。Ctrl+Cで終了。
// --stream-mmap=3の数値で確保するバッファサイズが変わる
// 数値が大きい方がバッファサイズ多いので取りこぼす確率が減る。
$ v4l2-ctl --stream-mmap=3 --stream-to=testrec.raw

// カメラがYUV形式で出力する場合、以下でffmpegでmp4に変換する。
// pix_fmt :
//   "YUYV 4:2:2" の場合 "yuyv422"
//   "YUYV 4:2:0" の場合 "yuv420p"
$ ffmpeg -f rawvideo -pix_fmt yuyv422 -video_size 640x480 -framerate 30 -i 'testrec.raw' -f mp4 -c:v h264_omx -b:v 768k 'testrec.mp4'

// カメラがMJPG(Motion JPEG)形式で出力する場合、以下でffmpegでmp4に変換する。
$ ffmpeg -i testrec.raw -vcodec libx264 testrec.mp4

-–stream-mmap=”3″の数値が小さくなるほど、フレームを取りこぼす確率が増えます。目標とするフレームレート(『v4l2-ctl -p 30』等で設定。上の方で記載しています)とPCのメモリとの兼ね合いで調整すると良いと思いますが、ほとんどの場合”3″で問題ないと思います。


もしffmpegでyuvをmp4に変換する際に、


Invalid buffer size, packet size 2048 < expected frame_size 460800


といったようなエラーが出る場合は、pix_fmt を正しいものにするか、動画自体を削除して再度撮影したものを使用して試してみるといいと思います。(私はその両方を見直してどうにかmp4変換・再生できました)


ただやはりいちいちyuvをmp4に変換するのは面倒なので、以下のようにして録画するのが手っ取り早いです。

// 動画撮影開始
$ ffmpeg \
  -f alsa -thread_queue_size 8192 -i hw:2,0 \
  -f v4l2 -thread_queue_size 8192 -s 640x480 -i /dev/video0 \
  -c:v h264_omx -b:v 768k \  
  -c:a aac \
  output.mp4 

// マイクがあることが前提なので、もしマイクなしのカメラを使用する場合は、
// 『-f alsa~』の行と、『-c:a acc』の行を削ってください。

もし、


[video4linux2,v4l2 @ 0x10bfe70] The V4L2 driver changed the video from 1920×1080 to 640×480


等と表示されて、解像度が意図したものにならない場合は、


$ v4l2-ctl -v width=1280,height=720,pixelformat=YUYV

の指定で、v4l2-ctlの解像度をffmpegで指定するものに合わせて、pixelformatをYUYVにして試してみてください。ffmpegで動画撮影開始前に、以下コマンドで正しく設定できているか確認すると良いと思います。

$ v4l2-ctl -V

ちなみにpixelformatがMJPG(Motion JPEG)の場合は、以下でffmpegで録画可能です。

//ffmpegでカメラからMJPG(Motion JPEG)で出力してmp4で保存

// まずpixelformatをMJPGに変更(設定済みであれば不要)
$ v4l2-ctl -v width=1920,height=1080,pixelformat=MJPG

// ffmpegで動画録画
$ ffmpeg \
    -f v4l2 -thread_queue_size 8192 -c:v mjpeg -s 1920x1080 -i /dev/video0 \
    -c:v h264_omx -b:v 768k \
    output01.mp4


// 録画できるにはできた。
// しかし、私の環境が Raspberry pi 4だからかフレーム落ちが酷かった。

コメント

このブログの人気の投稿

Raspberry Piでシリアル通信する方法(通信設定・通信確認)

Raspberry Pi Picoのステップ実行できる開発環境づくり