【開発奮闘記】MacでWebカメラ映像が乱れる！OpenCVのバグからハードウェア故障まで、原因を特定した全記録

こんにちは、Tech Samuraiです！
今回は、PythonとOpenCVを使ってMac miniに接続したWebカメラを制御する、という一見シンプルなプロジェクトで、私が経験した壮絶なトラブルシューティングの全記録を共有します。

最初は単なるコードのバグだと思っていた問題が、USBの物理的な接続、OSとハードウェアの相性、CPUの処理負荷、そして最後には予期せぬ結末へと、次々とその姿を変えていきました。

これは、エラーメッセージの裏に隠された真の原因を追い求めた、一人の開発者の探偵物語です。あなたのデバッグ作業のヒントが、この中にあるかもしれません。

フェーズ1：序章 – 最初の`AttributeError`

目的： PythonとOpenCVでUSBカメラに接続し、露出などのパラメータを制御する足がかりを作ること。

まず最初に遭遇したのは、AttributeError: module 'cv2' has no attribute 'CAP_PROP_AUTOWB'`というエラーでした。これは、OpenCVのバージョンによってプロパティ名の定義が微妙に違う（_`があったりなかったりする）ことが原因で、正しい名称cv2.CAP_PROP_AUTO_WBに修正することで、あっさり解決。この時点では、まだ楽観的でした。

フェーズ2：映像破損 – 緑と紫の帯との戦い

次に私を襲ったのが、本丸の問題でした。カメラから取得した映像に、緑や紫の**帯状のノイズ**が乗り、まともに表示されないのです。

初期仮説： ホワイトバランスなどの設定値がおかしいのでは？

しかし、いくらパラメータを調整しても改善しません。ここで私は一度コードから離れ、物理的な接続を見直すことにしました。カメラはMac miniに接続したドッキングステーションに繋いでいました。「もしや…？」と思い、カメラを**Mac mini本体のUSBポートに直接接続**したところ、ノイズは軽減されました。

真の原因①：データ転送量の問題
USBハブを経由することで帯域幅や電力が不足し、カメラからPCへの映像データが転送中に破損していたのです。

さらに、データ転送量を削減するため、圧縮効率の良い`MJPG`フォーマットを指定することで、映像は一旦、完全に安定しました。

# データ転送量を削減するためにMJPGフォーマットを指定
fourcc = cv2.VideoWriter_fourcc(*'MJPG')
cap.set(cv2.CAP_PROP_FOURCC, fourcc)

フェーズ3：制御不能 – 効かない設定とパフォーマンス低下

安定した映像は手に入りましたが、新たな問題が発生します。`cap.set()`で明るさなどを設定しても、全く映像に反映されないのです。`cap.get()`で値を確認すると、常に`0.0`が返ってきます。

真の原因②：ハードウェア制御の非対応
調査の結果、私の環境（Mac mini + macOS + Webカメラ + OpenCV）の組み合わせでは、**ハードウェアレベルでのリアルタイムなパラメータ制御に対応していない**ことが判明しました。

解決策（方針転換）：
ハードウェア制御を諦め、カメラから受け取ったフレーム（画像）を、**ソフトウェア側でリアルタイムに加工する**方針に切り替えました。OpenCVの関数を使えば、明るさや彩度の調整は可能です。

# 明るさ(alpha)とコントラスト(beta)をソフトウェアで調整
frame = cv2.convertScaleAbs(frame, alpha=alpha_value, beta=beta_value)

フェーズ4：CPUの悲鳴 – 処理負荷との最終決戦

ソフトウェア処理に切り替えたことで、新たな敵が現れました。色空間の変換など、CPUに負荷のかかる処理を追加した途端、あの忌まわしい**帯状のノイズが再発**したのです。

真の原因③：リアルタイム処理のボトルネック
これは、CPUの計算能力そのものというより、カメラから秒間30枚送られてくる高解像度のフレームを、Python/OpenCVの処理が捌ききれず、**データの渋滞**が発生している状態でした。

解決策：

リサイズによる負荷軽減：重い処理にかける前に、まずフレームを`cv2.resize()`で小さなサイズ（例: 640×480）に縮小。処理対象のピクセル数が激減し、CPU負荷が大幅に低下しました。
フレームレートの間引き：それでも処理が追いつかない場合、最終手段として「Nフレームに1回だけ重い処理を実行する」ようにし、CPUに十分な処理時間を確保しました。

これらの最適化により、ついにスクリプトは安定動作するようになりました。…そのはずでした。