Repository navigation
feat(hang): VR projection, stereo, and ambisonic catalog metadata #5543
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
aea9789
8b2c28b
58bf0a2
046a16e
29a5a61
510a337
3999384
351b830
eadbcbc
ed118c4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| use std::str::FromStr; | ||
|
|
||
| use derive_more::Display; | ||
|
|
||
| /// What a rendition's decoded channels carry, beyond the codec's own channel order. | ||
| /// | ||
| /// Absent means the codec's channel order. An unrecognized value decodes to | ||
| /// [`AudioLayout::Unknown`] instead of failing, and a consumer treats it as absent. | ||
| #[derive(Debug, Clone, PartialEq, Eq, Display)] | ||
| #[non_exhaustive] | ||
| pub enum AudioLayout { | ||
| /// Full-sphere ambisonics in AmbiX: ACN channel order with SN3D normalization. | ||
| /// | ||
| /// The order follows from the channel count, `(order + 1)²`, so the count is a square of at least 4. | ||
| #[display("ambisonic")] | ||
| Ambisonic, | ||
|
|
||
| /// A layout this build does not recognize, preserved verbatim. | ||
| #[display("{_0}")] | ||
| Unknown(String), | ||
| } | ||
|
|
||
| impl AudioLayout { | ||
| /// Refuse a channel count this layout cannot carry. | ||
| pub(crate) fn check(&self, channel_count: u32) -> crate::Result<()> { | ||
| if *self == Self::Ambisonic { | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a programmatic publisher sets AGENTS.md reference: rs/AGENTS.md:L42-L43 Useful? React with 👍 / 👎. |
||
| let order = channel_count.isqrt(); | ||
| if order < 2 || order * order != channel_count { | ||
| return Err(crate::Error::InvalidAmbisonicChannels(channel_count)); | ||
| } | ||
| } | ||
| Ok(()) | ||
| } | ||
| } | ||
|
|
||
| impl FromStr for AudioLayout { | ||
| type Err = crate::Error; | ||
|
|
||
| fn from_str(s: &str) -> Result<Self, Self::Err> { | ||
| Ok(match s { | ||
| "ambisonic" => Self::Ambisonic, | ||
| _ => Self::Unknown(s.to_string()), | ||
| }) | ||
| } | ||
| } | ||
|
|
||
| #[cfg(test)] | ||
| mod test { | ||
| use crate::catalog::{AudioCodec, AudioConfig}; | ||
|
|
||
| use super::*; | ||
|
|
||
| #[test] | ||
| fn round_trips() { | ||
| for (layout, json) in [ | ||
| (AudioLayout::Ambisonic, "ambisonic"), | ||
| (AudioLayout::Unknown("surround".to_string()), "surround"), | ||
| ] { | ||
| let mut config = AudioConfig::new(AudioCodec::Opus, 48_000, 4); | ||
| config.layout = Some(layout.clone()); | ||
| let encoded = serde_json::to_value(&config).unwrap(); | ||
| assert_eq!(encoded["layout"], json); | ||
| assert_eq!( | ||
| serde_json::from_value::<AudioConfig>(encoded).unwrap().layout, | ||
| Some(layout) | ||
| ); | ||
| } | ||
| } | ||
|
|
||
| #[test] | ||
| fn ambisonic_needs_a_square_channel_count() { | ||
| for channels in [4, 9, 16, 225] { | ||
| AudioLayout::Ambisonic.check(channels).unwrap(); | ||
| } | ||
| for channels in [0, 1, 2, 6, 8] { | ||
| assert!(matches!( | ||
| AudioLayout::Ambisonic.check(channels), | ||
| Err(crate::Error::InvalidAmbisonicChannels(c)) if c == channels | ||
| )); | ||
| } | ||
| // An unknown layout puts no constraint on the channel count. | ||
| AudioLayout::Unknown("surround".to_string()).check(6).unwrap(); | ||
| } | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When
ProjectionSchemasees a future projection such as{ kind: "cubemap", face: "front" }, this transform returns{ kind: "unknown", raw: ... }rather than the original wire object. A JS relay that republishes a parsed catalog passes it throughJson.Snapshot.Encoder.update(js/json/src/snapshot/encoder.ts:201-205), which parses and stringifies that wrapper; parsing the republished catalog then wraps it again. Rust'sUnknownProjectioninstead serializes the original object, so the implementations do not share the promised round-trip behavior. Keep the unknown output wire-shaped or unwraprawduring encoding.AGENTS.md reference: AGENTS.md:L111-L111
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Declining for this PR.
ProjectionSchemadeliberately copiesUnknownContainerSchemainjs/hang/src/catalog/container.ts, which has had the same{ kind: "unknown", raw }shape (and the same Rust/JS asymmetry) since unknown containers were added. The literalkindkeepskind === "equirectangular"narrowing, andrawis the documented way for a republisher to write the original back. No JS code reparses and republishes a catalog today:CatalogProducerbuilds its catalog from scratch and passes no schema to the encoder.If we want a parsed JS catalog to stringify back to its wire shape, the fix belongs in both schemas at once, so I'll suggest it as a follow-up rather than diverge the two here.
(Written by Claude Opus 5.5)