From a5b05d211e9f5fbcd8e3769b73c3621c4699c46c Mon Sep 17 00:00:00 2001 From: nkymut Date: Tue, 17 Dec 2024 17:28:53 +0800 Subject: [PATCH] Add DOC for devicemotion --- packages/motion/docs/devicemotion.mdx | 82 ++++++++++++++++++++++++ packages/motion/motion.mjs | 7 +- test/examples.test.mjs | 15 ----- website/src/config.ts | 1 + website/src/pages/learn/devicemotion.mdx | 10 +++ 5 files changed, 99 insertions(+), 16 deletions(-) create mode 100644 packages/motion/docs/devicemotion.mdx delete mode 100644 test/examples.test.mjs create mode 100644 website/src/pages/learn/devicemotion.mdx diff --git a/packages/motion/docs/devicemotion.mdx b/packages/motion/docs/devicemotion.mdx new file mode 100644 index 00000000..ebf1dbc4 --- /dev/null +++ b/packages/motion/docs/devicemotion.mdx @@ -0,0 +1,82 @@ +import { MiniRepl } from '../../../website/src/docs/MiniRepl'; +import { JsDoc } from '../../../website/src/docs/JsDoc'; + +# Device Motion + +Devicemotion module allows you to use your mobile device's motion sensors (accelerometer, gyroscope, and orientation sensors) to control musical parameters in real-time. This creates opportunities for expressive, movement-based musical interactions. + +## Basic Setup + +First, you need to enable device motion sensing: + + + +This will prompt the user for permission to access device motion sensors. + +## Available Motion Parameters + +You can access different types of motion data: + +| Motion | Long Names & Aliases | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| Acceleration | accelerationX (accX), accelerationY (accY), accelerationZ (accZ) | Measures linear acceleration of the device, excluding gravity. Raw values are normalized from g-force. | +| Gravity | gravityX (gravX), gravityY (gravY), gravityZ (gravZ) | Indicates device's orientation relative to Earth's gravity. Raw values are normalized from ±9.81 m/s². | +| Rotation | rotationAlpha (rotA, rotZ), rotationBeta (rotB, rotX), rotationGamma (rotG, rotY) | Measures rotation rate around each axis. Raw values (±180°/s) are normalized. | +| Orientation | orientationAlpha (oriA, oriZ), orientationBeta (oriB, oriX), orientationGamma (oriG, oriY) | Relative orientation from its starting device position. Normalized from:
- Alpha: 0° to 360°
- Beta: -180° to 180°
- Gamma: -90° to 90° | +| Absolute Orientation | absoluteOrientationAlpha (absOriA, absOriZ), absoluteOrientationBeta (absOriB, absOriX), absoluteOrientationGamma (absOriG, absOriY) | **Not available for iOS**
Earth-referenced orientation using magnetometer. Same normalization as Orientation. | + +Note: + +- All motion values are normalized to a range of 0 to 1. +- Not all devices have the same sensors available + Check [DeviceMotionEvent API](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent) for browser compatibility +- Refer to [Oritentation and motion data explained](https://developer.mozilla.org/en-US/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained) for more details + +### Orientation vs Absolute Orientation + +The key difference between regular orientation and absolute orientation is: + +- Regular orientation (`oriX/Y/Z`) measures relative changes in device orientation from its starting position +- Absolute orientation (`absOriX/Y/Z`) measures orientation relative to Earth's magnetic field and gravity, providing consistent absolute values regardless of starting position + +For example, if you rotate your device 90 degrees clockwise and then back: + +- Regular orientation will show a change during rotation but return to initial values +- Absolute orientation will show the actual compass heading throughout + +This makes absolute orientation particularly useful for creating direction-based musical interactions - for example, performers facing north could play one melody while those facing south play another, creating spatially-aware ensemble performances. Regular orientation, on the other hand, is better suited for detecting relative motion and gestures regardless of which direction the performer is facing. + +## Basic Example + +Here's a simple example that uses device motion to control a synthesizer: + + + +## Tips for Using Motion Controls + +1. Use `.range(min, max)` to map sensor values to musically useful ranges +2. Consider using `.segment()` to smooth out rapid changes in sensor values + +## Debugging + +You can use `segment(16).log()` to see the raw values from any motion sensor: + +```javascript +$_: accX.segment(16).log(); // logs acceleration values to the console +``` + +This is helpful when calibrating your ranges and understanding how your device responds to different movements. + +Remember that device motion works best on mobile devices and may not be available on all desktop browsers. Always test your motion-controlled pieces on the target device type! diff --git a/packages/motion/motion.mjs b/packages/motion/motion.mjs index f0a4fb41..875704ea 100644 --- a/packages/motion/motion.mjs +++ b/packages/motion/motion.mjs @@ -315,7 +315,12 @@ export const orientationX = orientationBeta; export const orientationY = orientationGamma; export const orientationZ = orientationAlpha; -// Short aliases for X,Y,Z +// Short aliases for A,B,G,X,Y,Z + +export const oriA = orientationAlpha; +export const oriB = orientationBeta; +export const oriG = orientationGamma; + export const oriX = orientationX; export const oriY = orientationY; export const oriZ = orientationZ; diff --git a/test/examples.test.mjs b/test/examples.test.mjs deleted file mode 100644 index 44ffdd5a..00000000 --- a/test/examples.test.mjs +++ /dev/null @@ -1,15 +0,0 @@ -import { queryCode } from './runtime.mjs'; -import { describe, it } from 'vitest'; -import doc from '../doc.json'; - -describe('runs examples', () => { - const { docs } = doc; - docs.forEach(async (doc) => { - doc.examples?.forEach((example, i) => { - it(`example "${doc.name}" example index ${i}`, async ({ expect }) => { - const haps = await queryCode(example, 4); - expect(haps).toMatchSnapshot(); - }); - }); - }); -}); diff --git a/website/src/config.ts b/website/src/config.ts index dd003c18..918c7b73 100644 --- a/website/src/config.ts +++ b/website/src/config.ts @@ -84,6 +84,7 @@ export const SIDEBAR: Sidebar = { { text: 'Music metadata', link: 'learn/metadata' }, { text: 'CSound', link: 'learn/csound' }, { text: 'Hydra', link: 'learn/hydra' }, + { text: 'Device Motion', link: 'learn/devicemotion' }, ], 'Pattern Functions': [ { text: 'Introduction', link: 'functions/intro' }, diff --git a/website/src/pages/learn/devicemotion.mdx b/website/src/pages/learn/devicemotion.mdx new file mode 100644 index 00000000..cd54a7cf --- /dev/null +++ b/website/src/pages/learn/devicemotion.mdx @@ -0,0 +1,10 @@ +--- +title: Device Motion +layout: ../../layouts/MainLayout.astro +--- + +import { MiniRepl } from '../../docs/MiniRepl'; +import { JsDoc } from '../../docs/JsDoc'; +import DeviceMotion from '../../../../packages/motion/docs/devicemotion.mdx'; + +