feat: add aspect ratio black-border correction for screen grabbers (hyperion-project#1301)

Adds a configurable "aspectRatio" option to all screen grabbers that
pads captured frames with black pillarboxes before LED mapping, so 4:3
content on 16:9 screens (or 16:9 on 21:9) is not incorrectly stretched
across the full LED ring. Implemented as a zero-cost passthrough when
disabled (the default).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tpmodding

assets/webconfig/i18n/en.json

@@ -438,6 +438,9 @@
   "edt_conf_flatbufServer_heading_title": "Flatbuffer Server",
   "edt_conf_flatbufServer_timeout_expl": "If no data is received for the given period, the component will be (soft) disabled.",
   "edt_conf_flatbufServer_timeout_title": "Timeout",
+  "edt_conf_fg_aspectRatio_title": "Aspect Ratio Correction",
+  "edt_conf_fg_aspectRatio_4_3_to_16_9": "4:3 → 16:9 (add pillarboxes)",
+  "edt_conf_fg_aspectRatio_16_9_to_21_9": "16:9 → 21:9 (add pillarboxes)",
   "edt_conf_fg_display_expl": "Select which desktop should be captured (multi monitor setup)",
   "edt_conf_fg_display_title": "Display",
   "edt_conf_fg_frequency_Hz_expl": "How fast new pictures are captured, i.e. it is the sampling rate. Note: The video might be played at a higher or lower frame rate.",

include/hyperion/GrabberWrapper.h

@@ -122,6 +122,7 @@ class GrabberWrapper : public QObject
 		int ret = grabber.grabFrame(_image);
 		if (ret >= 0)
 		{
+			applyAspectRatio();
 			emit systemImage(_grabberName, _image);
 			return true;
 		}
@@ -205,6 +206,8 @@ private slots:
 	void handleSourceRequestVideo(hyperion::Components component, int hyperionInd, bool listen);
 	void handleSourceRequestAudio(hyperion::Components component, int hyperionInd, bool listen);
 
+	void applyAspectRatio();
+
 	Grabber *_ggrabber;
 	QString _grabberName;
 
@@ -216,4 +219,10 @@ private slots:
 
 	/// The image used for grabbing frames
 	Image<ColorRgb> _image;
+
+	/// Reusable buffer for aspect ratio padding
+	Image<ColorRgb> _paddedImage;
+
+	/// Target aspect ratio for black-border padding (0 = disabled)
+	float _targetAspectRatio = 0.0f;
 };

libsrc/hyperion/GrabberWrapper.cpp

@@ -3,6 +3,9 @@
 #include <hyperion/Grabber.h>
 #include <HyperionConfig.h>
 
+// std
+#include <cstring>
+
 // utils includes
 #include <utils/GlobalSignals.h>
 #include <events/EventHandler.h>
@@ -263,6 +266,34 @@ void GrabberWrapper::setCropping(int cropLeft, int cropRight, int cropTop, int c
 	_ggrabber->setCropping(cropLeft, cropRight, cropTop, cropBottom);
 }
 
+void GrabberWrapper::applyAspectRatio()
+{
+	if (_targetAspectRatio <= 0.0f)
+		return;
+
+	const int srcW = _image.width();
+	const int srcH = _image.height();
+	// Round to nearest even number to keep stride well-aligned
+	const int dstW = (static_cast<int>(srcH * _targetAspectRatio) + 1) & ~1;
+
+	if (dstW <= srcW)
+		return;
+
+	if (_paddedImage.width() != dstW || _paddedImage.height() != srcH)
+		_paddedImage.resize(dstW, srcH);
+
+	_paddedImage.clear(ColorRgb::BLACK);
+
+	const int offsetX = (dstW - srcW) / 2;
+	const ColorRgb* src = _image.memptr();
+	ColorRgb*       dst = _paddedImage.memptr();
+
+	for (int y = 0; y < srcH; ++y)
+		memcpy(dst + y * dstW + offsetX, src + y * srcW, static_cast<size_t>(srcW) * sizeof(ColorRgb));
+
+	_image.swap(_paddedImage);
+}
+
 void GrabberWrapper::updateTimer(int interval)
 {
 	if(_updateInterval_ms != interval)
@@ -316,6 +347,16 @@ void GrabberWrapper::handleSettingsUpdate(settings::type type, const QJsonDocume
 				obj["cropBottom"].toInt(0));
 
 			_ggrabber->setFramerate(obj["fps"].toInt(DEFAULT_RATE_HZ));
+
+			// aspect ratio padding
+			const QString ar = obj["aspectRatio"].toString("disabled");
+			if (ar == "4:3-to-16:9")
+				_targetAspectRatio = 16.0f / 9.0f;
+			else if (ar == "16:9-to-21:9")
+				_targetAspectRatio = 21.0f / 9.0f;
+			else
+				_targetAspectRatio = 0.0f;
+
 			// eval new update time
 			updateTimer(_ggrabber->getUpdateInterval());
 

libsrc/hyperion/schema/schema-framegrabber.json

@@ -137,6 +137,20 @@
 			"default": 0,
 			"append": "edt_append_pixel",
 			"propertyOrder": 17
+		},
+		"aspectRatio": {
+			"type": "string",
+			"title": "edt_conf_fg_aspectRatio_title",
+			"enum": [ "disabled", "4:3-to-16:9", "16:9-to-21:9" ],
+			"options": {
+				"enum_titles": [
+					"edt_conf_enum_disabled",
+					"edt_conf_fg_aspectRatio_4_3_to_16_9",
+					"edt_conf_fg_aspectRatio_16_9_to_21_9"
+				]
+			},
+			"default": "disabled",
+			"propertyOrder": 18
 		}
 	},
 	"additionalProperties" : false