feat: add dynamic framerate control with intelligent clamping (v2.3.0)

Added comprehensive framerate control system with automatic hardware limit enforcement:

New Features:
- POST /v1/camera/framerate - Change framerate dynamically with smart clamping
- Automatic clamping to hardware maximum based on current resolution
- User-friendly API that never rejects requests, applies best available framerate
- Detailed response with requested vs applied framerate and clamping indicator

Enhanced Capabilities:
- GET /v1/camera/capabilities now includes:
  - current_framerate: Currently configured framerate
  - max_framerate_for_current_resolution: Max fps for active resolution
  - framerate_limits_by_resolution: Complete table of limits per resolution

Resolution-based Framerate Limits:
- 4K (3840x2160): max 30 fps
- 1440p (2560x1440): max 40 fps
- 1080p (1920x1080): max 50 fps
- 720p (1280x720): max 120 fps
- VGA (640x480): max 120 fps

Implementation:
- Added calculate_max_framerate() function based on pixel count
- Added set_framerate() method in CameraController with intelligent clamping
- State tracking for current width, height, and framerate
- Resolution changes now preserve current framerate setting

Testing:
- Added 3 new integration tests (16 total tests, all passing)
- test_capabilities_with_framerate_limits
- test_framerate_change_normal
- test_framerate_change_with_clamping

Documentation:
- Updated README.md with v2.3 features and usage examples
- Updated CHANGELOG.md with comprehensive v2.3.0 entry
- Added cURL and Python examples for framerate control
- API version bumped to 2.3.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Author: gmathy2104

CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to Pi Camera Service will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2025-11-22
+
+### Added
+
+#### Dynamic Framerate Control with Intelligent Clamping
+- `POST /v1/camera/framerate` - Change framerate dynamically with smart limit enforcement
+  - Automatically clamps requested framerate to hardware maximum for current resolution
+  - Returns detailed information about requested vs applied framerate
+  - Indicates with `clamped` flag when value was adjusted
+  - Example: Requesting 500fps at 4K automatically applies 30fps (the maximum for 4K)
+
+#### Framerate Limits in Capabilities
+- Enhanced `GET /v1/camera/capabilities` with framerate information:
+  - `current_framerate`: Currently configured framerate
+  - `max_framerate_for_current_resolution`: Maximum framerate for active resolution
+  - `framerate_limits_by_resolution`: Complete table of max fps per resolution
+    - 4K (3840x2160): 30fps max
+    - 1440p (2560x1440): 40fps max
+    - 1080p (1920x1080): 50fps max
+    - 720p (1280x720): 120fps max
+    - VGA (640x480): 120fps max
+
+### Changed
+- Resolution tracking now persists across camera reconfigurations
+- Updated test suite with 3 new comprehensive tests (now 16 tests total for v2.1+)
+
+### Documentation
+- Updated README.md with v2.3 framerate endpoint documentation
+- Added comprehensive CHANGELOG entry for v2.3
+
+## [2.2.0] - 2025-11-22
+
+### Added
+
+#### Camera Capabilities Discovery
+- `GET /v1/camera/capabilities` - New endpoint to query camera hardware capabilities
+  - Returns sensor model, supported resolutions, exposure/gain limits
+  - Lists all supported features (autofocus, noise reduction modes, etc.)
+  - Provides exposure value ranges and available control modes
+  - Essential for clients to discover what the camera supports
+
+#### Enhanced Status Information
+- `GET /v1/camera/status` now includes `current_limits` field
+  - Shows currently active frame duration and exposure limits
+  - Displays effective exposure limits based on hardware and configured constraints
+  - Helps understand why certain exposure values may not be achievable
+
+### Changed
+- Updated test suite with 2 new comprehensive tests (now 13 tests total for v2.1)
+
+### Documentation
+- Updated README.md with v2.2 capabilities endpoint
+- Added comprehensive CHANGELOG entry for v2.2
+
 ## [2.1.0] - 2025-11-22
 
 ### Added

README.md

@@ -2,15 +2,19 @@
 
 Production-ready **FastAPI** microservice for controlling Raspberry Pi Camera (libcamera/Picamera2) with **H.264 streaming** to **MediaMTX** via RTSP.
 
-**Version 2.1** - Advanced exposure controls, noise reduction, dynamic resolution, and low-light optimization!
+**Version 2.3** - Dynamic framerate control with intelligent clamping and comprehensive camera capabilities!
 
-[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
+[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
 [![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.121+-teal.svg)](https://fastapi.tiangolo.com/)
 [![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
 [![Tests](https://github.com/gmathy2104/pi-camera-service/workflows/Tests/badge.svg)](https://github.com/gmathy2104/pi-camera-service/actions)
 
-> 🆕 **New in v2.1**: Exposure value (EV) compensation, noise reduction modes, advanced AE controls (constraint/exposure modes), AWB mode presets, autofocus trigger, dynamic resolution change, and corrected exposure limits! Perfect for low-light scenarios.
+> 🆕 **New in v2.3**: Dynamic framerate control with intelligent clamping! Request any framerate and the API automatically applies the maximum for your resolution. Enhanced capabilities endpoint with complete framerate limits table.
+>
+> ℹ️ **v2.2 features**: Camera capabilities discovery endpoint to query supported resolutions, exposure/gain limits, and available features.
+>
+> ℹ️ **v2.1 features**: Exposure value (EV) compensation, noise reduction modes, advanced AE controls, AWB mode presets, autofocus trigger, dynamic resolution change.
 >
 > ℹ️ **v2.0 features**: Autofocus control, snapshot capture, manual AWB with NoIR presets, image processing, HDR support, ROI/digital zoom, day/night detection. See [docs/upgrade-v2.md](docs/upgrade-v2.md).
 
@@ -166,6 +170,44 @@ This service runs **on the Raspberry Pi**, controls the camera (e.g., Raspberry
   - `./scripts/set-normal-mode.sh` - Reset to defaults
 - **Documentation**: See [docs/low-light-modes.md](docs/low-light-modes.md)
 
+### Advanced Features (v2.2) 🆕
+
+#### 📊 Camera Capabilities Discovery
+- **Hardware discovery**: Query camera sensor model, resolution, and supported features
+- **Exposure/gain limits**: Get minimum and maximum values for exposure and gain
+- **Feature detection**: Discover what controls are available (autofocus, HDR, etc.)
+- **Resolution support**: List all supported streaming resolutions
+- **Essential for clients**: Know what the camera supports before configuring
+- **Endpoint**: `GET /v1/camera/capabilities`
+
+#### 📈 Enhanced Status Information
+- **Current limits**: See active frame duration and exposure constraints
+- **Effective limits**: Understand why certain exposure values may not apply
+- **Real-time constraints**: Monitor hardware and configured limits
+- **Enhanced field**: `current_limits` in `GET /v1/camera/status`
+
+### Advanced Features (v2.3) 🆕
+
+#### 🎬 Dynamic Framerate Control with Intelligent Clamping
+- **Independent framerate adjustment**: Change framerate without changing resolution
+- **Smart limit enforcement**: Automatically clamps to hardware maximum for current resolution
+- **User-friendly**: No rejected requests - API applies best available framerate
+- **Detailed feedback**: Returns requested vs applied framerate with clamping indicator
+- **Resolution-aware limits**:
+  - 4K (3840x2160): max 30 fps
+  - 1440p (2560x1440): max 40 fps
+  - 1080p (1920x1080): max 50 fps
+  - 720p (1280x720): max 120 fps
+  - VGA (640x480): max 120 fps
+- **Example**: Request 500fps at 4K → API applies 30fps (the maximum) and indicates clamping occurred
+- **Endpoint**: `POST /v1/camera/framerate`
+
+#### 📊 Complete Framerate Limits Table
+- **Enhanced capabilities**: `GET /v1/camera/capabilities` now includes:
+  - `current_framerate`: Currently configured framerate
+  - `max_framerate_for_current_resolution`: Maximum fps for active resolution
+  - `framerate_limits_by_resolution`: Complete table of max fps for each resolution
+
 The video stream is published to MediaMTX, which then serves it via **RTSP / WebRTC / HLS**.
 
 ---
@@ -339,7 +381,7 @@ sudo journalctl -u pi-camera-service -f
   "status": "healthy",
   "camera_configured": true,
   "streaming_active": true,
-  "version": "2.0.0"
+  "version": "2.3.0"
 }
 ```
 
@@ -365,7 +407,63 @@ sudo journalctl -u pi-camera-service -f
   "day_night_mode": "auto",
   "day_night_threshold_lux": 10.0,
   "frame_duration_us": 33321,
-  "sensor_black_levels": [4096, 4096, 4096, 4096]
+  "sensor_black_levels": [4096, 4096, 4096, 4096],
+
+  // New v2.2 field
+  "current_limits": {
+    "frame_duration_us": 33321,
+    "frame_duration_limits_us": null,
+    "effective_exposure_limit_us": {
+      "min": 100,
+      "max": 1000000
+    }
+  }
+}
+```
+
+### Camera Capabilities (New in v2.2, Enhanced in v2.3)
+
+**GET** `/v1/camera/capabilities`
+
+Discover camera hardware capabilities and supported features.
+
+```json
+{
+  "sensor_model": "imx708",
+  "sensor_resolution": {
+    "width": 4608,
+    "height": 2592
+  },
+  "supported_resolutions": [
+    {"width": 640, "height": 480, "label": "VGA"},
+    {"width": 1280, "height": 720, "label": "720p"},
+    {"width": 1920, "height": 1080, "label": "1080p"},
+    {"width": 2560, "height": 1440, "label": "1440p"},
+    {"width": 3840, "height": 2160, "label": "4K"}
+  ],
+  "exposure_limits_us": {"min": 100, "max": 1000000},
+  "gain_limits": {"min": 1.0, "max": 16.0},
+  "lens_position_limits": {"min": 0.0, "max": 15.0},
+  "exposure_value_range": {"min": -8.0, "max": 8.0},
+  "supported_noise_reduction_modes": ["off", "fast", "high_quality", "minimal", "zsl"],
+  "supported_ae_constraint_modes": ["normal", "highlight", "shadows", "custom"],
+  "supported_ae_exposure_modes": ["normal", "short", "long", "custom"],
+  "supported_awb_modes": ["auto", "tungsten", "fluorescent", "indoor", "daylight", "cloudy", "custom"],
+  "features": [
+    "auto_exposure", "manual_exposure", "auto_white_balance", "manual_white_balance",
+    "exposure_value_compensation", "noise_reduction", "ae_constraint_modes",
+    "ae_exposure_modes", "awb_modes", "image_processing", "roi_digital_zoom",
+    "exposure_limits", "autofocus", "lens_position_control", "autofocus_trigger"
+  ],
+  "current_framerate": 30.0,
+  "max_framerate_for_current_resolution": 50.0,
+  "framerate_limits_by_resolution": [
+    {"width": 3840, "height": 2160, "label": "4K", "max_fps": 30.0},
+    {"width": 2560, "height": 1440, "label": "1440p", "max_fps": 40.0},
+    {"width": 1920, "height": 1080, "label": "1080p", "max_fps": 50.0},
+    {"width": 1280, "height": 720, "label": "720p", "max_fps": 120.0},
+    {"width": 640, "height": 480, "label": "VGA", "max_fps": 120.0}
+  ]
 }
 ```
 
@@ -473,6 +571,57 @@ sudo journalctl -u pi-camera-service -f
 }
 ```
 
+### Dynamic Framerate Control (v2.3)
+
+**POST** `/v1/camera/framerate`
+
+Change camera framerate dynamically with intelligent clamping. The API automatically applies the hardware maximum for your current resolution, ensuring a user-friendly experience without rejected requests.
+
+**Request**:
+```json
+{
+  "framerate": 60.0,           // Desired framerate (1-1000 fps)
+  "restart_streaming": true    // Restart streaming after change (default: true)
+}
+```
+
+**Response**:
+```json
+{
+  "status": "ok",
+  "requested_framerate": 60.0,
+  "applied_framerate": 50.0,    // Actual framerate applied (may be clamped)
+  "max_framerate_for_resolution": 50.0,
+  "resolution": "1920x1080",
+  "clamped": true               // Indicates if framerate was clamped to max
+}
+```
+
+**Example - Requesting high framerate at 4K**:
+```bash
+# Request 500fps at 4K resolution
+curl -X POST http://raspberrypi:8000/v1/camera/framerate \
+  -H "Content-Type: application/json" \
+  -d '{"framerate": 500}'
+
+# Response: API automatically clamps to 30fps (4K maximum)
+# {
+#   "status": "ok",
+#   "requested_framerate": 500.0,
+#   "applied_framerate": 30.0,
+#   "max_framerate_for_resolution": 30.0,
+#   "resolution": "3840x2160",
+#   "clamped": true
+# }
+```
+
+**Resolution-based framerate limits**:
+- 4K (3840x2160): max 30 fps
+- 1440p (2560x1440): max 40 fps
+- 1080p (1920x1080): max 50 fps
+- 720p (1280x720): max 120 fps
+- VGA (640x480): max 120 fps
+
 ### Streaming Control
 
 **POST** `/v1/streaming/start`
@@ -555,6 +704,11 @@ curl -X POST http://raspberrypi:8000/v1/camera/roi \
   -H "Content-Type: application/json" \
   -d '{"x": 0.25, "y": 0.25, "width": 0.5, "height": 0.5}'
 
+# Change framerate (v2.3) - intelligent clamping
+curl -X POST http://raspberrypi:8000/v1/camera/framerate \
+  -H "Content-Type: application/json" \
+  -d '{"framerate": 60}'
+
 # With authentication (if CAMERA_API_KEY is set)
 curl -H "X-API-Key: your-key" \
   http://raspberrypi:8000/v1/camera/status
@@ -612,6 +766,19 @@ requests.post(
     },
     headers=HEADERS
 )
+
+# Change framerate (v2.3) with intelligent clamping
+response = requests.post(
+    f"{BASE_URL}/v1/camera/framerate",
+    json={"framerate": 60},
+    headers=HEADERS
+)
+result = response.json()
+if result['clamped']:
+    print(f"Framerate clamped: {result['requested_framerate']}fps → {result['applied_framerate']}fps")
+    print(f"Max for {result['resolution']}: {result['max_framerate_for_resolution']}fps")
+else:
+    print(f"Framerate set to {result['applied_framerate']}fps")
 ```
 
 ### JavaScript / TypeScript

VERSION

@@ -1 +1 @@
-2.1.0
+2.3.0