Connect audio, MIDI, media, and teamwork

Source: Documentation/MediaAsset.md

Overview

MediaAsset is the catalog record for an uploaded, generated, analyzed, hosted, or externally referenced media object. It separates:

• metadata and access rules in Doctrine;
• file bytes at a path or URL;
• optional typed classification through MediaAssetType;
• optional tool-specific metadata and audio analysis;
• personal, teacher, or band audience context.

A database row does not prove that the file is locally managed or currently reachable. path can describe a managed public upload or an external/non-managed location. Deletion logic intentionally distinguishes those cases.

Upload Pipeline

The web upload route requires:

• authenticated user;
• paid-feature write access;
• valid media_upload CSRF token;
• at least one uploaded file.

Files are stored under:

public/uploads/media/{YYYY}/{MM}/u{userId}/

The filename is:

{slugified-original-base}-{4 random bytes as hex}.{validated-extension}

For each file:

1. UploadSecurityValidator validates upload integrity, size, extension, and detected MIME;
2. the file is moved to its managed path;
3. size and SHA-256 checksum are calculated from the stored file;
4. image dimensions are read when applicable;
5. a MediaAssetInput is passed to the same processor used by API writes;
6. a failed database/processor step removes the just-moved file.

Upload metadata includes:

{
  "originalName": "source filename",
  "uploadedVia": "media_library_form"
}

Upload Security

General media uploads are capped at:

100 MiB

Avatar uploads use a separate 5 MiB cap and a narrower extension/MIME policy.

Validation uses server-observed file state and MIME detection. Client-provided MIME and filename alone are not trusted.

Authorization

MediaAssetVoter defines:

MEDIA_ASSET_VIEW
MEDIA_ASSET_EDIT
MEDIA_ASSET_DELETE

Rules:

• public assets: anyone can view;
• owner: view/edit/delete;
• application admin/super admin: view/edit/delete;
• linked team member: view only;
• everyone else: denied.

The processor separately requires paid write access, plan-compatible audience, team membership for selected teams, and quota capacity.

Troubleshooting

Row exists but file is unavailable

The path may be external, stale, or no longer present. Database persistence does not verify permanent remote availability.

Delete leaves a file behind

The path may be non-managed or shared by another row. Both behaviors are intentional.

Band upload falls back to solo

The web form normalizes unsupported audience choices. Confirm band subscription and at least one selected team membership.

API returns not found for a known ID

The current user cannot see that asset under public/owner/team rules.

Kind differs from submitted kind

An attached MediaAssetType code is authoritative.

Quota rejection after replacing a file

Inspect owner and every newly/shared team's projected file count and byte usage; quota is enforced across both scopes.

Source: Documentation/daw/JolyEngineDawDefaults.md

Track Layout

| Track | Role | MIDI channel | Suggested DAW device | | --- | --- | ---: | --- | | Joly Harmony | Chords, pads, comping | 1 | Poly synth, electric piano, or pad | | Joly Bass | Bass roots and slash-chord bass | 2 | Mono bass | | Joly Guide | Guide tones and scale runners | 3 | Soft lead | | Joly Accent | Pulse notes and rhythmic stabs | 4 | Short pluck | | Joly FX | Impacts, risers, texture | 5 | Sampler or one-shot rack | | Joly Melody | Melody maker | 6 | Lead synth or melodic instrument | | Joly Solo | Solo improviser | 7 | Lead synth | | Joly Drums | Drum clock and kit hits | 10 | Drum rack, Drum Machine Designer, or GM kit |

Shared MIDI CCs

| CC | Meaning | Target | | ---: | --- | --- | | 1 | Modulation | Performance intensity | | 2 | Breath | Phrase dynamics | | 7 | Volume | Track level | | 10 | Pan | Track pan | | 11 | Expression | Phrase volume | | 64 | Sustain | Hold harmony and melody notes | | 71 | Resonance | Filter resonance | | 74 | Brightness | Filter cutoff | | 91 | Reverb | Reverb send | | 93 | Chorus | Delay or chorus send |

Remote-control CCs are reserved on channel 16:

| CC | Target | | ---: | --- | | 20 | Master level | | 21 | Bass level | | 22 | Harmony level | | 23 | Melody level | | 24 | Drums level | | 25 | JolyEngine complexity | | 26 | Bars per chord | | 27 | Style select | | 28 | Pattern select | | 29 | Include drums | | 30 | Include FX | | 31 | Panic / all notes off |

Source: Documentation/mobile/MobileMediaAssetsApi.md

Metadata & Caching

Persist the following fields when present:

| Field | Mobile use | | :--- | :--- | | id, title, nameSlug | Stable identity, list labels, and local route keys. | | kind, mediaAssetType | Preview and playback routing. | | audience, isPublic, teams, owner, quota | Visibility and feature-gate decisions. | | mimeType, extension, path | Binary loading and fallback preview detection. | | byteSize, checksum | Offline storage budgeting and content verification. | | durationMs, pageCount, widthPx, heightPx | Player, document, and image layout sizing. | | metadata, trackContainer | Structured tool-specific payloads and sequencer state. | | audioAnalysis | Radial pulse intensity and waveform summaries during playback. | | createdAt, updatedAt | Sync freshness and cache ordering. |

Use checksum for content-addressed files when it is available. If no checksum is present, cache by media asset id plus updatedAt.

Offline Rules

• Download binaries lazily for playback, preview, or explicit offline pinning.
• Never pre-download every media asset from bootstrap or aggregate sync.
• Keep offline files under a visible user budget.
• Keep metadata rows after a failed binary download so lists and retry actions still work.
• On 304 Not Modified, keep the existing Room rows and cached files.

Source: Documentation/mobile/MobileAudioEngineInterface.md

Clock Ownership

The audio engine owns musical transport while playing. UI animation, Room, WorkManager, WebView timers, and wall-clock time must not schedule notes.

Use a monotonic frame/host clock and integer musical ticks:

transport: bpm, ppq, beatsPerBar, beatUnit, loopTicks
position: absoluteTick, loopTick, framePosition, monotonicTimeNanos

Phase zero is loop tick zero. The renderer maps normalized phase to the 12 o'clock top anchor; this visual convention must not alter audio timing.

Scheduling

• Convert ticks to frames using the current tempo segment and sample rate.
• Retain integer/rational values as long as possible to avoid accumulated float drift.
• Schedule ahead by a bounded horizon appropriate to the backend.
• Support different ring subdivisions from a common master transport; do not require every ring to have 16 steps.
• Define behavior for tempo change: immediate, next beat, next bar, or next loop.
• Define note-off ownership so stop, seek, route loss, and lifecycle interruption cannot leave stuck voices.