Skip to content

Latest commit

 

History

History
222 lines (187 loc) · 12.1 KB

3DS.md

File metadata and controls

222 lines (187 loc) · 12.1 KB

New Nintendo 3DS

The upper screen displays video. The lower screen provides fixed tiles for play/pause, ten-second skips, progress, volume and the queue. Browsing the queue keeps the video mounted. Touch scrubbing previews a position on the device and sends one seek when the contact ends. L/R skip, START toggles playback, B switches to browsing, X opens search, and A activates the focused control.

The layout follows the separated viewing and control areas in Samsung Flex mode and the continuity guidance in Apple's Designing for iPhone Duo. It uses explicit tiles sized for a 320×240 resistive touch display. Search uses the PocketJS system keyboard in its contact layout: 30-pixel-high keys on phone-style staggered rows. This is an adaptation of those interaction principles, not a reproduction of an iPhone interface.

Install and connect

Requirements: New 3DS with a homebrew environment, ftpd, a working NDSP setup, Bun, yt-dlp and FFmpeg on the Mac, Docker, and the Rust toolchain requested by the vendored PocketJS build. MVD decoding requires New 3DS hardware. Unsupported hardware produces a visible playback error.

Before first playback, press L + D-pad Down + SELECT to open Luma3DS Rosalina, then choose Miscellaneous options → Dump DSP firmware. This writes /3ds/dspfirm.cdc from the console's firmware. Without that file or a Homebrew Launcher DSP handle, NDSP returns 0xd880a7fa and playback stops at audio initialization. After dumping the firmware, return to the player and choose Retry. See the devkitPro audio setup.

bun run setup
bun run 3ds
# While ftpd is open; use the IP and port shown on its screen:
bun run deploy:3ds --host 192.168.8.102 --ftp-port 5000
# Launch /3ds/pocket-youtube.3dsx in the Homebrew Launcher, then:
bun run serve:3ds --device 192.168.8.102

The installer preserves an existing application pairing key, backs up a previous launcher, and reads back the uploaded binary. Its receipt is .pocket/last-deploy-3ds.json. It does not replace another app's key or the device-wide Runtime key. --advertise <Mac IPv4> selects the media interface when the Mac has several networks. The device and Mac need access to each other on the LAN. The companion uses authenticated port 8741 for commands and a ticketed TCP endpoint for media.

bun run 3ds --cia also builds an installable CIA. A native ABI change requires reinstalling the launcher; a guest package alone cannot install a decoder.

Execution and bandwidth

Work Owner
YouTube search, TLS, format resolution Companion worker, shared yt-dlp adapter
Scaling, H.264 rate control, audio encoding Companion FFmpeg and block encoder
H.264 decode and RGB565 conversion New 3DS MVD service
Texture scaling and presentation PICA200
Audio output and playback clock NDSP
Input, progress preview, pause and volume Device guest/native handoff

The stream uses 512×256 baseline H.264 at 30 fps, 650 kbps target video rate, 750 kbps maximum rate, no B-frames, and a one-second keyframe interval. Each frame contains one complete VCL slice. The encoder uses one thread and disables sliced threading; slices=1 alone does not override the zero-latency preset's thread-based splitting. That splitting caused MVD to reject the second slice of the first frame with 0x17005 on hardware. Source aspect ratio is fitted to the 400×240 display before encoding. Stereo 22.05 kHz ADPCM uses about 177 kbps. A three-second moving test pattern measured 854,712 bit/s including packet headers, with 90 decodable video frames. That is a software fixture measurement; it does not establish real Wi-Fi or physical playback performance.

The paired offload channel carries bounded metadata and asynchronous job polls. Media bytes never enter JSON. Eight consumer credits, fixed native queues, and a 300 ms audio prebuffer bound queued work. Disconnect closes the old stream. After a new authenticated session, the app resolves a fresh source and resumes its selected video at the remembered position.

The lower screen uses baked silver navigation chrome, a fine gray texture, beveled transport buttons, white result rows and the framework keyboard's classic theme. Official YouTube vector outlines are rasterized without changing their aspect ratio; artwork/youtube/README.md records their source and bun run bake:classic reproduces the assets.

An empty list shows a recessed search card with a touch action and an X-key hint. The card changes its title and description while connecting, searching, or displaying an empty result. Touching the card opens the search keyboard.

Titles do not wait for thumbnail downloads. Each title and channel uses one 192×36 coverage response, preserving CJK text on baked-font devices. Each 72×40 color thumbnail uses one 16-color indexed response. Both fit the 2,500-byte offload payload bound. Two worker downloads run at once; image decoding uses the companion's canvas library without spawning FFmpeg per thumbnail.

The existing PocketJS resource runtime owns a 1.5 MiB texture cache, up to 32 entries, two active reads, one read start and one materialization per frame. Visible titles have priority over thumbnails and adjacent-row prefetch. A row that unmounts withdraws demand; its ready texture remains until cache eviction. Pending thumbnail polls back off from six to sixty frames. Playback commands use the offload client outside the resource queue, with four tickets reserved.

Search pages follow Pocket Doc's query-and-offset resource identity. The companion owns two bounded query snapshots and streams up to twenty search results per fill. A page becomes readable after five rows arrive; requests for the same page share the snapshot. The next fill retains prior row order and removes duplicate video IDs. Failed fills do not advance the page position.

Scrolling predicts page demand before the end of the list. The app requests one next page when three rows of base lookahead reach the loaded boundary; downward velocity can add five rows of lookahead. Metadata uses the same resource scheduler as artwork, ahead of thumbnail work. Reconnect clears page state for the new companion session. No selectable pagination row is mounted.

The search keyboard is PocketJS's system keyboard (@pocketjs/framework/osk) rendered on the auxiliary surface with the classic theme. The surface reports contacts, so the framework picks the staggered layout and the down-edge press model: a character types on the down edge, release clears the pressed cap, backspace repeats while held, holding space drags the caret, and a second shift press within 0.35 s locks caps. The d-pad focus ring stays hidden until the first d-pad press. B cancels, START commits, L switches the number layer and R shifts. The keyboard remembers its layer and key across opens. Now Playing uses a baked arrow image rather than a Unicode icon outside the device font's coverage.

PSP and Vita run the single-screen presentation with the same classic chrome: glossy title bar, white host-rendered rows with a blue selection wash, and the same keyboard in its grid layout for the d-pad. They retain their color-card and stream adapters.

Capability ownership and validation

One pocket.json describes every device. Its dual-screen presentation is addressed to the modality { "screens": 2, "touch": "auxiliary" }: the resolver derives the 3DS profile's modality, selects that entry (app/main-dual.tsx), resolves its 400×240 top and 320×240 auxiliary viewports, and admits display.auxiliary, input.touch.auxiliary, media.playback and io.offload on top of the app-level capabilities. The PSP and Vita derive to one screen and compile the baseline app/main.tsx. The compiler walks each bundle from its entry, so the 3DS artwork and the PSP card code never share a bundle. Application UI code does not call MVD, NDSP or device SDK functions. Shared store actions, source resolution, search, card text rasterization and scrubber state serve both presentations (docs/MODALITY.md in PocketJS states the model).

One companion data layer serves both devices. host/companion-worker.ts answers search pages (youtube.search), artwork (youtube.artwork) and playback commands over PocketJS offload. The 3DS reaches it over TCP (bun run serve:3ds); the PSP reaches the same worker over the PSPLINK share through the USB offload provider (bun run serve:psp), where video uses the .pkst ring under pocket-svc/youtube/. Rows on both devices are demand-driven resources requested for the list's visible window (ClassicList.onWindow), so a d-pad walk to the end pages in without a sentinel press.

PocketJS owns native media playback, ticketed streaming, the bounded audio format, surface-aware keyboards, auxiliary WASM rendering, resource lifetime and bounded indexed-image uploads. The service client owns transport selection, job polling, deadlines and reconnect. The media provider owns native pause, ring control, end polling, stream files and the playback clock. The app requests artwork through the provider image loader. YouTube search, video selection, encoding policy and the lower-screen layout belong here.

bun run typecheck
bun run test
bun run test:3ds
bun run 3ds

The dual-screen test boots the real application bundle, drives lower-screen keyboard input and controls, verifies one-seek-per-drag and reconnect, and writes software renders into out/dual-screen/. Its media host is a test double. Physical decoding, sustained frame rate, audio sync, network recovery and touch acceptance require a separate device receipt. The companion logs decoder, presentation, buffer, byte and underrun counters every two seconds.

The software journeys cover keyboard input, paging, playback, pause, seeking, back navigation and reconnect. The user confirmed the preceding 0.3.0 build's 3DS acceptance on September 16. Provider refactoring has a separate software validation receipt; that confirmation does not establish a new physical run.

The color correction selects MVD_OUTPUT_BGR565, the MVD output format used by the devkitPro example for the GPU's RGB565 packing. MVD's RGB565 selection exchanged red and blue. The companion retains the source colors; a real H.264 encode/decode regression checks red, green, blue, yellow and a skin-tone patch. Physical color and input acceptance are recorded after installing the new native launcher.

Manual releases

Run Release 3DS in the repository's Actions tab with the main branch, or:

gh workflow run release-3ds.yml --repo pocket-nexus/pocket-youtube --ref main

Only a manual dispatch publishes a release. The workflow builds the commit selected at dispatch and uses that run's creation date in Asia/Shanghai for the vYYYY.MM.DD tag, for example v2026.09.23. The embedded Pocket manifest uses the same date as SemVer (2026.9.23); these runner-local changes are not committed. Application IDs and CIA title IDs stay fixed. The CIA title-version field retains the vendored packager's value; the calendar version belongs to the release and embedded application manifest.

Each release contains pocket-youtube-vYYYY.MM.DD.3dsx, pocket-youtube-vYYYY.MM.DD.cia, SHA256SUMS and build-info.json. The build record identifies the source commit, PocketJS pin, application version and Actions run. Verify downloaded binaries with sha256sum --check SHA256SUMS (macOS: shasum -a 256 -c SHA256SUMS).

One release is allowed per calendar day. An existing tag or release blocks another run for that date, including reruns after publication. Failed builds can be rerun and keep their original date. If an upload or publication fails after creating a draft, inspect and delete that incomplete draft and any matching unpublished tag before rerunning. Published assets are not replaced.

Pull requests use the same build workflow to produce both formats as an Actions artifact, without publishing a release. CI checks compilation, binary headers and checksums; console boot and interaction require device validation.