Initial import
This commit is contained in:
Matteo Benedetto
@@ -0,0 +1,104 @@
|
||||
# Copilot Instructions
|
||||
|
||||
## Product Goal
|
||||
|
||||
Build a balanced, production-oriented first milestone for an R36S DLNA browser with Wi-Fi support.
|
||||
|
||||
The application must:
|
||||
|
||||
- run on R36S-class Linux firmware derived from ArkOS
|
||||
- use Python for the application logic
|
||||
- use SDL2 for the user interface and input handling
|
||||
- discover DLNA/UPnP media servers on the local LAN
|
||||
- allow hierarchical browsing of remote media content
|
||||
- support local playback on the device
|
||||
- stay lightweight enough for RK3326-class hardware
|
||||
|
||||
## Balanced Development Plan
|
||||
|
||||
Copilot should follow this plan unless the user explicitly changes priorities.
|
||||
|
||||
### Phase 1 - Project Bootstrap
|
||||
|
||||
- Create a clean Python project layout with a package entrypoint.
|
||||
- Keep dependencies minimal and explicit.
|
||||
- Prefer simple run scripts and documentation that also make sense on-device.
|
||||
|
||||
### Phase 2 - DLNA Discovery And Browsing
|
||||
|
||||
- Implement SSDP discovery for media servers in the LAN.
|
||||
- Filter and normalize DLNA MediaServer devices.
|
||||
- Build a ContentDirectory client for browsing containers and media items.
|
||||
- Support pagination, caching, and safe handling of incomplete metadata.
|
||||
|
||||
### Phase 3 - SDL2 User Interface
|
||||
|
||||
- Design the UI for 640x480 with readable typography and low visual overhead.
|
||||
- Optimize navigation for D-pad controls with A/B and shoulder buttons.
|
||||
- Keep the UI responsive while network operations run asynchronously.
|
||||
|
||||
### Phase 4 - Milestone 2: Integrated GStreamer Playback
|
||||
|
||||
- Implement playback through GStreamer inside the application process instead of launching an external player subprocess.
|
||||
- Prefer the system GStreamer stack via `PyGObject` and `GstPlayBin` rather than custom decode loops.
|
||||
- Prefer decoding video to `GstAppSink` and rendering frames through SDL2 so playback does not depend on a window manager, native overlay sinks, or X11 embedding.
|
||||
- Support play, pause/resume, stop, relative seek, automatic return to browser on end-of-stream, and explicit error reporting when decode or frame upload fails.
|
||||
- Keep the architecture ready for follow-up work on on-screen playback HUD, resume state, and device-specific video backend tuning.
|
||||
|
||||
### Phase 5 - Milestone 3: SDL Video Viewport, HUD, and Wayland Compatibility
|
||||
|
||||
- Reserve an explicit video viewport inside the SDL window and scale decoded video to that viewport instead of using the full window surface.
|
||||
- Render a full playback HUD in SDL around the video area, including title, state, elapsed/duration, progress, volume, cache/buffer hints, resolution, and visible controls.
|
||||
- Make the playback HUD controllable with the same device inputs used elsewhere in the app, at minimum covering pause/resume, stop, seek, and volume.
|
||||
- Prefer SDL backends that work without a window manager on target hardware, especially `kmsdrm` on R36S-class devices.
|
||||
- If the chosen frame upload path is too slow on target hardware, optimize within the SDL-rendered path rather than falling back to external overlay windows.
|
||||
|
||||
### Phase 6 - Device Integration And Hardening
|
||||
|
||||
- Handle Wi-Fi instability, timeouts, malformed XML, missing thumbnails, and unsupported media.
|
||||
- Keep memory use and redraw frequency conservative.
|
||||
- Document firmware assumptions, runtime prerequisites, and launch steps.
|
||||
|
||||
### Phase 7 - Validation
|
||||
|
||||
- Add focused tests for parsing, navigation state, and non-UI logic.
|
||||
- Verify manually on a real LAN and, when possible, on the target device.
|
||||
- Prefer incremental, testable milestones over broad unfinished features.
|
||||
|
||||
## State Tracking Requirements
|
||||
|
||||
Copilot must treat development state as a living artifact, not as implicit context.
|
||||
|
||||
- Track the current milestone, completed work, in-progress work, blockers, and next steps.
|
||||
- Keep a repository status file updated during development at `docs/development-status.md`.
|
||||
- Update that status file whenever a meaningful implementation step is completed, re-scoped, or blocked.
|
||||
- Record only verified state, not guesses.
|
||||
- Keep status entries concise, factual, and ordered by relevance to current work.
|
||||
- If the plan changes, update both the active implementation and the tracked status.
|
||||
|
||||
The status file should normally include:
|
||||
|
||||
- current milestone
|
||||
- current architecture decisions
|
||||
- completed tasks
|
||||
- tasks in progress
|
||||
- blockers or open questions
|
||||
- next recommended actions
|
||||
|
||||
## Implementation Preferences
|
||||
|
||||
- Favor simple, explicit modules over premature abstraction.
|
||||
- Separate SDL2 UI concerns from networking and playback concerns.
|
||||
- Keep async/network code isolated behind small adapters.
|
||||
- Avoid features that increase complexity before the core browsing flow is stable.
|
||||
- Prefer integrated GStreamer playback over subprocess control for Milestone 2.
|
||||
- Prefer SDL-rendered playback from decoded frames over platform-specific window embedding on R36S-class targets.
|
||||
- For Milestone 3, keep video and HUD in the same SDL render pass so the design remains compatible with DRM/KMS-only environments.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
- Fix root causes when practical.
|
||||
- Avoid unrelated refactors.
|
||||
- Preserve performance on low-end ARM hardware.
|
||||
- Make every milestone runnable, not just partially scaffolded.
|
||||
- Treat documentation and development-state tracking as part of the deliverable.
|
||||
Reference in New Issue
Block a user