Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 116 additions & 0 deletions .github/workflows/fc-spatial-quality-verify.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
name: FC Spatial Audio — isolated quality validation

on:
pull_request:
branches: [main]
paths:
- 'fc/spatial-audio/experimental/**'
- '.github/workflows/fc-sync-release.yml'
- '.github/workflows/fc-spatial-quality-verify.yml'
workflow_dispatch:

permissions:
contents: read

concurrency:
group: fc-spatial-verify-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
verify-quality-engine:
runs-on: ubuntu-latest
timeout-minutes: 90
steps:
- name: Checkout proposed sources
uses: actions/checkout@v4
with:
fetch-depth: 0
lfs: true

- name: JDK 17
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '17'

- name: Gradle cache
uses: gradle/actions/setup-gradle@v4

- name: Install native Android tools
shell: bash
run: |
set -euo pipefail
SDKM="${ANDROID_HOME:-/usr/local/lib/android/sdk}/cmdline-tools/latest/bin/sdkmanager"
yes | "$SDKM" --licenses > /dev/null || true
"$SDKM" 'cmake;3.22.1' 'ndk;27.0.12077973'

- name: Install icon resizing dependency
run: python3 -m pip install --user Pillow

- name: Apply the regular, then experimental, spatial overlays
shell: bash
run: |
set -euo pipefail
export FC_VERSION_CODE="$(sed -n 's/^versionCode=//p' fc/version.properties)"
export FC_VERSION_NAME="$(sed -n 's/^versionName=//p' fc/version.properties)"
python3 fc/apply-overlay.py
python3 fc/spatial-audio/apply.py
python3 fc/spatial-audio/experimental/apply.py
python3 fc/branding/apply.py

- name: Fill missing Android locale fallbacks for this build
run: |
python3 - <<'PY'
import copy
import xml.etree.ElementTree as ET
from pathlib import Path

base_path = Path("app/src/main/res/values/strings.xml")
base_root = ET.parse(base_path).getroot()
supported = {"string", "plurals", "string-array"}
base_entries = {}
for element in list(base_root):
name = element.attrib.get("name")
if (element.tag in supported and name
and element.attrib.get("translatable") != "false"):
if name in base_entries:
raise SystemExit(f"Duplicate base Android resource: {name}")
base_entries[name] = element

for qualifier in ("values-in", "values-ko"):
locale_path = Path("app/src/main/res") / qualifier / "strings.xml"
locale_tree = ET.parse(locale_path)
locale_root = locale_tree.getroot()
locale_entries = {}
for element in list(locale_root):
name = element.attrib.get("name")
if element.tag in supported and name:
locale_entries.setdefault(name, []).append(element)

added = 0
for name, base_element in base_entries.items():
existing = locale_entries.get(name, [])
if any(item.attrib.get("translatable") != "false" for item in existing):
continue

# Replace a locale-specific translatable=false placeholder if one
# exists; otherwise append the same English fallback Android
# would resolve at runtime. Existing translations are untouched.
for item in existing:
locale_root.remove(item)
locale_root.append(copy.deepcopy(base_element))
added += 1

if added:
locale_tree.write(locale_path, encoding="utf-8", xml_declaration=True)
ET.parse(locale_path) # Fail here if generated XML is malformed.
print(f"{qualifier}: added {added} English fallback entries for this build.")
PY

- name: Run all production unit tests, including new audio regressions
run: |
set -euo pipefail
chmod +x gradlew
FC_VERSION_CODE="$(sed -n 's/^versionCode=//p' fc/version.properties)" \
FC_VERSION_NAME="$(sed -n 's/^versionName=//p' fc/version.properties)" \
./gradlew :app:testProdReleaseUnitTest --no-daemon --stacktrace
24 changes: 23 additions & 1 deletion .github/workflows/fc-sync-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,13 @@ jobs:
set -euo pipefail
CURRENT_UPSTREAM_VERSION="$(sed -n 's/^upstreamVersion=//p' fc/version.properties)"
VERSION_NAME="$(sed -n 's/^versionName=//p' fc/version.properties)"
EXPERIMENT_ENABLED="$(sed -n 's/^enabled=//p' fc/spatial-audio/experimental/config.properties)"
LAST_EXPERIMENT_ENABLED="$(sed -n 's/^experimentalAudio=//p' fc/version.properties)"
LAST_EXPERIMENT_ENABLED="${LAST_EXPERIMENT_ENABLED:-false}"
if [[ "$EXPERIMENT_ENABLED" != "true" && "$EXPERIMENT_ENABLED" != "false" ]]; then
echo "Invalid experimental spatial audio flag" >&2
exit 1
fi
if [[ -z "$CURRENT_UPSTREAM_VERSION" || -z "$VERSION_NAME" ]]; then
echo "Missing FC upstreamVersion/versionName metadata." >&2
exit 1
Expand All @@ -152,7 +159,7 @@ jobs:
release_asset_exists=true
fi

if [[ "$UPSTREAM_VERSION" != "$CURRENT_UPSTREAM_VERSION" || "$UPSTREAM_CHANGED" == "true" ]]; then
if [[ "$UPSTREAM_VERSION" != "$CURRENT_UPSTREAM_VERSION" || "$UPSTREAM_CHANGED" == "true" || "$EXPERIMENT_ENABLED" != "$LAST_EXPERIMENT_ENABLED" ]]; then
# A new stable series starts at .1; new main commits in that series increment the FC revision.
python3 fc/bump-version.py "$UPSTREAM_VERSION"
should_release=true
Expand All @@ -167,6 +174,11 @@ jobs:
should_release=false
fi

if [[ "$should_release" == "true" ]]; then
# Record the shipped variant after a release is selected; flag changes bump version.
sed -i '/^experimentalAudio=/d' fc/version.properties
printf 'experimentalAudio=%s\n' "$EXPERIMENT_ENABLED" >> fc/version.properties
fi
VERSION_CODE="$(sed -n 's/^versionCode=//p' fc/version.properties)"
VERSION_NAME="$(sed -n 's/^versionName=//p' fc/version.properties)"
echo "should_release=$should_release" >> "$GITHUB_OUTPUT"
Expand Down Expand Up @@ -252,6 +264,14 @@ jobs:
echo "included=true" >> "$GITHUB_OUTPUT"
fi

- name: Apply temporary Spatial Audio quality experiment
id: spatial_quality
if: steps.decision.outputs.should_release == 'true'
shell: bash
run: |
set -euo pipefail
python3 fc/spatial-audio/experimental/apply.py
echo "enabled=$(sed -n 's/^enabled=//p' fc/spatial-audio/experimental/config.properties)" >> "$GITHUB_OUTPUT"
- name: Fill missing Android locale fallbacks for this build
if: steps.decision.outputs.should_release == 'true'
run: |
Expand Down Expand Up @@ -442,6 +462,7 @@ jobs:
app/src/main/java/com/music/zenith/playback/SpatialAudioDecisionEngine.kt
app/src/main/java/com/music/zenith/TopBarActionVisibility.kt
app/src/test/java/com/music/zenith/playback/SpatialAudioLearningTest.kt
app/src/test/java/com/music/zenith/playback/SpatialAudioQualityTest.kt
app/src/test/java/com/music/zenith/playback/SpatialAudioPreferenceTest.kt
app/src/test/java/com/music/zenith/playback/SpatialAudioDecisionEngineTest.kt
)
Expand Down Expand Up @@ -510,6 +531,7 @@ jobs:
- Includes ${{ steps.upstream.outputs.commits_ahead }} upstream commits beyond the stable baseline when built as a main snapshot.
- FC Zenith follows upstream main automatically. Every new source snapshot must pass tests, build and signature verification before publishing.
- The same FC signing certificate is checked before publishing.
- Experimental DSP quality layer: ${{ steps.spatial_quality.outputs.enabled }} (reversible; includes audio regression tests).
- Spatial Audio: ${{ steps.spatial_audio.outputs.included == 'true' && 'Includes the persistent FC stereo learner, binary per-track On/Off with Auto status, and phone-speaker/Atmos/DSP safety bypasses. Profiles and explicit feedback remain on-device.' || 'Not included in this build.' }}

Obtainium source: https://github.com/Batmancpu/FCZenith
Expand Down
55 changes: 55 additions & 0 deletions fc/spatial-audio/experimental/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Temporary FC Spatial Audio quality experiment

This layer is **optional and removable**. It is applied only to the generated
Android sources in the GitHub Actions build workspace, *after*
`fc/spatial-audio/apply.py`. The existing tested permanent FC Spatial Audio
engine is preserved byte-for-byte in `fc/spatial-audio/SpatialAudioProcessor.kt`
and `SpatialAudioLearning.kt`.

## What changes when enabled

- Reduce mid/side gain from 2.5 to 2.0 and crossfeed from 0.20 to 0.16; shorten
crossfeed delay to 12 ms to reduce aggressive image expansion.
- Calculate the one-pole crossfeed low-pass from a 1.6-kHz cutoff and the actual
sample rate instead of reusing a fixed coefficient at 44.1/48/96 kHz.
- Add a common-L/R, fast-attack sample-peak limiter with 0.98 ceiling and
250-ms release. It protects the DSP path while preserving a bit-exact bypass
when disabled. This is **not a true-peak/oversampling limiter**; real-device
listening and intersample-peak verification remain necessary.
- Remove per-block ByteBuffer duplication during PCM16 analysis and replace
delay ring modulo with a wrap comparison. Publish completed audio-profile
fingerprints on one bounded pre-started worker, not on the audio callback.
- Increase the effective-independent-evidence requirement from 3.0 to 3.5 and
raise the Auto On/Off confidence gates to 80% / 85%, respectively. Existing
explicit On/Off choices and all safety bypasses remain authoritative.
- Add `SpatialAudioQualityTest.kt` to the production unit-test suite covering
sample peaks and numeric safety across 44.1/48/96 kHz, PCM16 bypass and
limiting, bit-exact disabled Float32, mono bypass, background completion,
toggling and conservative Auto learning.

## Release and rollback

Set `enabled=true` in `config.properties` to opt in. Set `enabled=false`
to return to the original FC Spatial Audio implementation. Committing a flag
change to main triggers a new numbered release, with strictly increasing
Android versionCode and unchanged signing certificate, app package, brrMusic
branding, Fluid Cloud compatibility and existing preferences.

The workflow restores every generated Kotlin file and test to the upstream
checkout before committing to main. The stable integration assets themselves
remain unchanged. Missing exact patch anchors abort the release.

## QA evidence and limitations

CI unit tests and an APK build can establish compilation, the algorithmic
sample-peak ceiling, deterministic bypass and release signing. They cannot
certify subjective sound quality, perceptual spaciousness, end-to-end true
peaks or device-specific output behavior.

Before declaring this engine the preferred permanent version, perform A/B
listening against the baseline signed APK on wired headphones, Bluetooth and
USB DAC, with low and high volumes. Verify phone-speaker and Dolby Atmos
bypasses, Fluid Cloud and crossfade behavior on physical devices. Look for
vocal coloration, pumping, fatigue, clipping and dropouts. If regressions
appear, switch the flag off and issue a new release without changing
upstream application code.
Loading
Loading