diff --git a/tools/chatgui/src/video_frame_image.h b/tools/chatgui/src/video_frame_image.h
index 007b1cff..eceb8c23 100644
--- a/tools/chatgui/src/video_frame_image.h
+++ b/tools/chatgui/src/video_frame_image.h
@@ -1,5 +1,12 @@
 /* RGB888 для sws_scale: FFmpeg выделяет выровненные строки и запас для SIMD.
- * QImage разделяет буфер без копирования; последний владелец освобождает AVFrame. */
+ * Доступен только при HAVE_FFMPEG. width/height — положительные размеры в пикселях;
+ * ошибка allocation/геометрии даёт пустой QImage с ERROR(video), ресурсов у вызывающего нет.
+ * Успех — QImage::Format_RGB888 с AVFrame stride (выравнивание 32), память не инициализирована:
+ * перед показом заполнить видимые пиксели. Для sws_scale брать bits()/bytesPerLine()
+ * свежего, ещё не разделяемого image. Qt detach создаёт свой буфер без этих гарантий SIMD.
+ * Копии QImage разделяют буфер без копирования; последний владелец исходного буфера
+ * освобождает AVFrame через cleanup callback. Освобождать bits() вручную нельзя.
+ * Отдельные изображения можно создавать в разных потоках; совместную запись исключает вызывающий. */
 #pragma once
 
 #ifdef HAVE_FFMPEG