V3 file parsing

docs/README.md

@@ -7,6 +7,7 @@
 - [Getting started](getting-started.md)
 - [Data model and sensor channels](data-model.md)
 - [API reference](api-reference.md)
+- [Parser internals](parser-internals.md)
 
 ## Package Scope
 

docs/api-reference.md

@@ -146,11 +146,22 @@ Returns one sensor DataFrame by name.
 - Valid names: `imu`, `barometer`, `microphone`, `ppg`, `optical_temp`, `bone_acc`
 - Raises `KeyError` for unknown names.
 
+#### `get_sampling_rate(sensor: str | int) -> Optional[float]`
+
+Returns the default sampling rate for a sensor name or SID when the file header
+contains v3+ frequency metadata. Returns `None` for v2 files or sensors without
+frequency metadata.
+
+#### `get_sampling_rates() -> Dict[str, Optional[float]]`
+
+Returns default sampling rates for all known dataset sensors keyed by sensor
+name. Values are `None` when metadata is unavailable.
+
 #### `get_dataframe() -> pandas.DataFrame`
 
 Builds and caches a merged DataFrame across all non-empty sensor streams.
 
-#### `get_audio_dataframe(sampling_rate: int = 48000) -> pandas.DataFrame`
+#### `get_audio_dataframe(sampling_rate: Optional[float] = None) -> pandas.DataFrame`
 
 Returns timestamp-indexed audio DataFrame with columns:
 
@@ -159,6 +170,9 @@ Returns timestamp-indexed audio DataFrame with columns:
 
 Behavior:
 
+- Uses the microphone sampling rate from v3+ file headers when available.
+- Falls back to 48 kHz when no microphone sampling-rate metadata is present.
+- Uses the caller-provided `sampling_rate` as an explicit override.
 - Raises `ValueError` if `sampling_rate <= 0`.
 - Returns empty DataFrame with expected columns if no mic packets exist.
 - Caches by sampling rate.
@@ -173,11 +187,11 @@ Saves the combined DataFrame to CSV if `self.df` is non-empty.
 
 Call `get_dataframe()` first to ensure `self.df` is populated.
 
-#### `play_audio(sampling_rate: int = 48000) -> None`
+#### `play_audio(sampling_rate: Optional[float] = None) -> None`
 
 Plays audio in IPython/Jupyter via `IPython.display.Audio`.
 
-#### `save_audio(path: str, sampling_rate: int = 48000) -> None`
+#### `save_audio(path: str, sampling_rate: Optional[float] = None) -> None`
 
 Writes WAV audio with `scipy.io.wavfile.write`.
 

docs/data-model.md

@@ -26,7 +26,7 @@ All sensor DataFrames are indexed by `timestamp` in seconds (`float`), derived f
 
 ## Accessor Semantics
 
-Each sensor is exposed as a `_SensorAccessor` object:
+Each sensor is exposed as a `SensorAccessor` object:
 
 - `sensor.df` or `sensor.to_dataframe()` returns the full sensor DataFrame with original column names.
 - Group columns are available as sub-DataFrames:
@@ -59,3 +59,8 @@ The audio DataFrame generated by `get_audio_dataframe()` uses:
 
 - index: `timestamp` in seconds
 - columns: `mic.inner`, `mic.outer`
+
+When a v3+ file header provides microphone frequency metadata, the default audio
+timestamps use that sampling rate. Recordings without microphone frequency
+metadata fall back to 48 kHz, and callers can still pass `sampling_rate` to
+override the default.

docs/getting-started.md

@@ -65,7 +65,7 @@ mag_z = dataset.imu.mag.z
 
 ```python
 # Timestamp-indexed stereo audio DataFrame
-audio_df = dataset.get_audio_dataframe()  # default 48_000 Hz
+audio_df = dataset.get_audio_dataframe()  # header mic rate, or 48_000 Hz fallback
 print(audio_df.columns)  # mic.inner, mic.outer
 
 # Save WAV