recs 0.2.0__tar.gz → 0.3.0__tar.gz

{recs-0.2.0 → recs-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: recs
-Version: 0.2.0
+Version: 0.3.0
 Summary: 🎙 recs: the Universal Recorder 🎙
 License: MIT
 Author: Tom Ritchford
@@ -10,9 +10,10 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: coverage
 Requires-Dist: dtyper
-Requires-Dist: humanfriendly (>=10.0,<11.0)
+Requires-Dist: humanfriendly
 Requires-Dist: impall
 Requires-Dist: numpy
 Requires-Dist: overrides
@@ -20,9 +21,9 @@ Requires-Dist: pyaudio
 Requires-Dist: rich
 Requires-Dist: sounddevice
 Requires-Dist: soundfile
-Requires-Dist: strenum (>=0.4.15,<0.5.0)
-Requires-Dist: threa
-Requires-Dist: tomli (>=2.0.1,<3.0.0)
+Requires-Dist: strenum
+Requires-Dist: threa (>=1.9.0)
+Requires-Dist: tomli
 Requires-Dist: typer
 Description-Content-Type: text/markdown
 
@@ -60,13 +61,13 @@ has been used to mitigate and minimize this through software.  See Appendix A.
 
 ### Universal?
 
-It is a "Universal Recorder" because I plan to be able to record all streams of data in
-some coherent way.
+It is a "Universal Recorder" because the plan to be able to record all streams of data:
+audio is simply the start.
 
-I have already [written code](https://github.com/rec/litoid) to do this for
-MIDI and DMX and I'll be folding that in in due time, but most of the difficulty
-and most of the value in this first step is the audio, so I have focused on just audio
-for this first release!
+I have already [written code](https://github.com/rec/litoid) to do this for MIDI and DMX
+- it works well but it isn't productionized, and I'll be folding that in in due time,
+but most of the difficulty and most of the value in this first step is the audio, so I
+have focused on just audio for this first release!
 
 It might be that video is also incorporated in the far future, but the tooling is just
 not there for Python yet, and it would be much too heavy to sit in the background all
@@ -75,12 +76,53 @@ Recorder if you liked.
 
 ### Installation
 
-Use
-
-### Usage
-
-
-
+`recs` is a standard PyPi package - use `poetry add recs` or `pip install recs` or your
+favorite package manager.
+
+To test, type `recs --info`, which prints JSON describing the input devices
+you have. Here's a snippet from my machine:
+
+```
+[
+    {
+        "name": "FLOW 8 (Recording)",
+        "index": 1,
+        "hostapi": 0,
+        "max_input_channels": 10,
+        "max_output_channels": 4,
+        "default_low_input_latency": 0.01,
+        "default_low_output_latency": 0.004354166666666667,
+        "default_high_input_latency": 0.1,
+        "default_high_output_latency": 0.0136875,
+        "default_samplerate": 48000.0
+    },
+    {
+        "name": "USB PnP Sound Device",
+        "index": 2,
+        ...
+    },
+    ...
+]
+```
+
+### Basic Usage
+
+Pick your nicest terminal program, go to a favorite directory with some free space, and
+type:
+
+```
+recs
+```
+
+`recs` will start recording all the active audio channels into your current directory
+and display the results in the terminal.
+
+What "active"means can be customized rather a lot, but by default when a channel becomes
+too quiet for more than a short time, it stops recording, and will start a new recording
+automatically when the channel receives a signal.
+
+Some care is taken to preserve the quiet before the start or after the end of a
+recording to prevent abrupt transitions.
 
 
 #### Appendix A: Failure modes

{recs-0.2.0 → recs-0.3.0}/README.md

@@ -32,13 +32,13 @@ has been used to mitigate and minimize this through software.  See Appendix A.
 
 ### Universal?
 
-It is a "Universal Recorder" because I plan to be able to record all streams of data in
-some coherent way.
+It is a "Universal Recorder" because the plan to be able to record all streams of data:
+audio is simply the start.
 
-I have already [written code](https://github.com/rec/litoid) to do this for
-MIDI and DMX and I'll be folding that in in due time, but most of the difficulty
-and most of the value in this first step is the audio, so I have focused on just audio
-for this first release!
+I have already [written code](https://github.com/rec/litoid) to do this for MIDI and DMX
+- it works well but it isn't productionized, and I'll be folding that in in due time,
+but most of the difficulty and most of the value in this first step is the audio, so I
+have focused on just audio for this first release!
 
 It might be that video is also incorporated in the far future, but the tooling is just
 not there for Python yet, and it would be much too heavy to sit in the background all
@@ -47,12 +47,53 @@ Recorder if you liked.
 
 ### Installation
 
-Use
-
-### Usage
-
-
-
+`recs` is a standard PyPi package - use `poetry add recs` or `pip install recs` or your
+favorite package manager.
+
+To test, type `recs --info`, which prints JSON describing the input devices
+you have. Here's a snippet from my machine:
+
+```
+[
+    {
+        "name": "FLOW 8 (Recording)",
+        "index": 1,
+        "hostapi": 0,
+        "max_input_channels": 10,
+        "max_output_channels": 4,
+        "default_low_input_latency": 0.01,
+        "default_low_output_latency": 0.004354166666666667,
+        "default_high_input_latency": 0.1,
+        "default_high_output_latency": 0.0136875,
+        "default_samplerate": 48000.0
+    },
+    {
+        "name": "USB PnP Sound Device",
+        "index": 2,
+        ...
+    },
+    ...
+]
+```
+
+### Basic Usage
+
+Pick your nicest terminal program, go to a favorite directory with some free space, and
+type:
+
+```
+recs
+```
+
+`recs` will start recording all the active audio channels into your current directory
+and display the results in the terminal.
+
+What "active"means can be customized rather a lot, but by default when a channel becomes
+too quiet for more than a short time, it stops recording, and will start a new recording
+automatically when the channel receives a signal.
+
+Some care is taken to preserve the quiet before the start or after the end of a
+recording to prevent abrupt transitions.
 
 
 #### Appendix A: Failure modes

{recs-0.2.0 → recs-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "recs"
-version = "0.2.0"
+version = "0.3.0"
 description = "🎙 recs: the Universal Recorder 🎙"
 authors = ["Tom Ritchford <tom@swirly.com>"]
 license = "MIT"
@@ -14,14 +14,14 @@ pyaudio = "*"
 rich = "*"
 sounddevice = "*"
 soundfile = "*"
-threa = "*"
+threa = ">=1.9.0"
 typer = "*"
 impall = "*"
 overrides = "*"
 coverage = "*"
-strenum = "^0.4.15"
-humanfriendly = "^10.0"
-tomli = "^2.0.1"
+strenum = "*"
+humanfriendly = "*"
+tomli = "*"
 
 [tool.poetry.group.dev.dependencies]
 black = "*"
@@ -39,10 +39,14 @@ build-backend = "poetry.core.masonry.api"
 [tool.coverage.run]
 branch = true
 source = ["recs"]
-omit = ["recs/cfg/cli.py"]
+omit = [
+    "recs/__main__.py",
+    "recs/cfg/cli.py",
+    "recs/cfg/app.py",
+]
 
 [tool.coverage.report]
-fail_under = 97
+fail_under = 94
 skip_covered = true
 exclude_lines = [
     "pragma: no cover",
@@ -67,7 +71,7 @@ warn_unused_ignores = true
 
 [tool.black]
 skip-string-normalization = true
-target-version = ["py311"]
+target-version = ["py310"]
 
 [tool.isort]
 profile = "black"

recs-0.3.0/recs/__main__.py

@@ -0,0 +1,29 @@
+import sys
+
+import click
+
+from recs.base import RecsError
+from recs.cfg import app, cli
+
+assert cli
+
+
+def run() -> int:
+    try:
+        app.app(prog_name='recs', standalone_mode=False)
+        return 0
+
+    except RecsError as e:
+        print('ERROR:', *e.args, file=sys.stderr)
+
+    except click.ClickException as e:
+        print(f'{e.__class__.__name__}: {e.message}', file=sys.stderr)
+
+    except click.Abort:
+        print('Interrupted', file=sys.stderr)
+
+    return -1
+
+
+if __name__ == '__main__':
+    sys.exit(run())

{recs-0.2.0 → recs-0.3.0}/recs/audio/block.py

@@ -37,7 +37,7 @@ class Block:
 
     @cached_property
     def volume(self) -> float:
-        return sum(self.amplitude) / len(self.amplitude) / self.scale
+        return sum(self.amplitude) / len(self.amplitude)
 
     @cached_property
     def channel_count(self) -> int:
@@ -45,7 +45,7 @@ class Block:
 
     @cached_property
     def amplitude(self) -> np.ndarray:
-        return (self.max - self.min) / 2
+        return (self.max - self.min) / (2 * self.scale)
 
     @cached_property
     def max(self) -> np.ndarray:
@@ -99,6 +99,3 @@ class Blocks:
 
     def __getitem__(self, i: int) -> Block:
         return self.blocks[i]
-
-    def __len__(self) -> int:
-        return len(self.blocks)

recs-0.3.0/recs/audio/channel_writer.py

@@ -0,0 +1,194 @@
+import contextlib
+import typing as t
+from datetime import datetime
+from pathlib import Path
+from threading import Lock
+
+from overrides import override
+from soundfile import SoundFile
+from threa import Runnable
+
+from recs.base.state import ChannelState
+from recs.base.types import SDTYPE, Active, Format, SdType
+from recs.cfg import Cfg, Track, device, time_settings
+from recs.misc import counter, file_list
+
+from .block import Block, Blocks
+from .file_opener import FileOpener
+from .header_size import header_size
+
+URL = 'https://github.com/rec/recs'
+
+BUFFER = 128
+FORMAT_TO_SIZE_LIMIT = {
+    Format.aiff: 0x8000_0000,
+    Format.wav: 0x1_0000_0000,
+}
+
+ITEMSIZE = {
+    SdType.float32: 4,
+    SdType.int16: 2,
+    SdType.int32: 4,
+}
+
+BLOCK_FUZZ = 2
+
+
+class ChannelWriter(Runnable):
+    bytes_in_this_file: int = 0
+
+    frames_in_this_file: int = 0
+    frames_written: int = 0  # Used elsewhere
+
+    largest_file_size: int = 0
+    longest_file_frames: int = 0
+
+    timestamp: float = 0
+
+    _sf: SoundFile | None = None
+
+    @property
+    def active(self) -> Active:
+        return Active.active if self._sf else Active.inactive
+
+    def __init__(
+        self, cfg: Cfg, times: time_settings.TimeSettings[int], track: Track
+    ) -> None:
+        super().__init__()
+
+        self.do_not_record = cfg.dry_run or cfg.calibrate
+        self.format = cfg.format
+        self.metadata = cfg.metadata
+        self.times = times
+        self.track = track
+
+        self._blocks = Blocks()
+        self._lock = Lock()
+
+        self.files_written = file_list.FileList()
+        self.frame_size = ITEMSIZE[cfg.sdtype or SDTYPE] * len(track.channels)
+        self.longest_file_frames = times.longest_file_time
+        self.opener = FileOpener(cfg, track)
+        self._volume = counter.MovingBlock(times.moving_average_time)
+
+        if not cfg.infinite_length:
+            largest = FORMAT_TO_SIZE_LIMIT.get(cfg.format, 0)
+            self.largest_file_size = max(largest - BUFFER, 0)
+
+    def update(self, update: device.Update) -> ChannelState:
+        block = Block(update.array[:, self.track.slice])
+        with self._lock:
+            return self._receive_block(block, update.timestamp)
+
+    @override
+    def stop(self) -> None:
+        with self._lock:
+            self.running = False
+            self._write_and_close()
+            self.stopped = True
+
+    def _close(self) -> None:
+        sf, self._sf = self._sf, None
+        if sf and sf.frames and sf.frames >= self.times.shortest_file_time:
+            sf.close()
+        elif sf:
+            with contextlib.suppress(Exception):
+                sf.close()
+            with contextlib.suppress(Exception):
+                Path(sf.name).unlink()
+
+    def _open(self, offset: int) -> SoundFile:
+        timestamp = self.timestamp - offset / self.track.device.samplerate
+        ts = datetime.fromtimestamp(timestamp)
+
+        index = 1 + len(self.files_written)
+
+        metadata = {'date': ts.isoformat(), 'software': URL, 'tracknumber': str(index)}
+        metadata |= self.metadata
+
+        self.bytes_in_this_file = header_size(metadata, self.format)
+        self.frames_in_this_file = 0
+
+        sf = self.opener.create(metadata, timestamp, index)
+        self.files_written.append(Path(sf.name))
+        return sf
+
+    def _receive_block(self, block: Block, timestamp: float) -> ChannelState:
+        saved_state = self._state(
+            max_amp=max(block.max) / block.scale,
+            min_amp=min(block.min) / block.scale,
+        )
+
+        dt = self.timestamp - timestamp
+        self.timestamp = timestamp
+        self._volume(block)
+
+        if not self.do_not_record and (self._sf or not self.stopped):
+            expected_dt = len(block) / self.track.device.samplerate
+
+            if dt > expected_dt * BLOCK_FUZZ:  # We were asleep, or otherwise lost time
+                self._write_and_close()
+
+            self._blocks.append(block)
+
+            if block.volume >= self.times.noise_floor_amplitude:
+                if not self._sf:  # Record some quiet before the first block
+                    length = self.times.quiet_before_start + len(self._blocks[-1])
+                    self._blocks.clip(length, from_start=True)
+
+                self._write_blocks(self._blocks)
+                self._blocks.clear()
+
+            if self.stopped or self._blocks.duration > self.times.stop_after_quiet:
+                self._write_and_close()
+
+        return self._state() - saved_state
+
+    def _state(self, **kwargs) -> ChannelState:
+        return ChannelState(
+            file_count=len(self.files_written),
+            file_size=self.files_written.total_size,
+            is_active=bool(self._sf),
+            recorded_time=self.frames_written / self.track.device.samplerate,
+            timestamp=self.timestamp,
+            volume=tuple(self._volume.mean()),
+            **kwargs,
+        )
+
+    def _write_and_close(self) -> None:
+        # Record some quiet after the last block
+        removed = self._blocks.clip(self.times.quiet_after_end, from_start=False)
+
+        if self._sf and removed:
+            self._write_blocks(reversed(removed))
+
+        self._close()
+
+    def _write_blocks(self, blox: t.Iterable[Block]) -> None:
+        blocks = list(blox)
+
+        # The last block in the list ends at self.timestamp so
+        # we keep track of the sample offset before that
+        offset = -sum(len(b) for b in blocks)
+
+        for b in blocks:
+            # Check if this block will overrun the file size or length
+            remains: list[int] = []
+
+            if self.longest_file_frames:
+                remains.append(self.longest_file_frames - self.frames_in_this_file)
+
+            if self._sf and self.largest_file_size:
+                file_bytes = self.largest_file_size - self.bytes_in_this_file
+                remains.append(file_bytes // self.frame_size)
+
+            if remains and min(remains) <= len(b):
+                self._close()
+
+            self._sf = self._sf or self._open(offset)
+            self._sf.write(b.block)
+            offset += len(b)
+
+            self.frames_in_this_file += len(b)
+            self.frames_written += len(b)
+            self.bytes_in_this_file += len(b) * self.frame_size

{recs-0.2.0 → recs-0.3.0}/recs/audio/file_opener.py

@@ -1,9 +1,10 @@
+import itertools
 from pathlib import Path
 
 import soundfile as sf
 
 from recs.cfg import Cfg, Track
-from recs.misc.recording_path import recording_path
+from recs.cfg.metadata import ALLOWS_METADATA
 
 
 class FileOpener:
@@ -27,23 +28,21 @@ class FileOpener:
             subtype=self.cfg.subtype,
         )
 
-        for k, v in metadata.items():
-            setattr(fp, k, v)
+        if self.cfg.format in ALLOWS_METADATA:
+            for k, v in metadata.items():
+                setattr(fp, k, v)
 
         return fp
 
-    def create(self, metadata: dict[str, str], timestamp: float) -> sf.SoundFile:
-        index = 0
-        suffix = ''
-        path, name = recording_path(
-            self.track, self.cfg.aliases, self.cfg.subdirectory, timestamp
-        )
+    def create(
+        self, metadata: dict[str, str], timestamp: float, index: int
+    ) -> sf.SoundFile:
+        p = Path(self.cfg.path.evaluate(self.track, self.cfg.aliases, timestamp, index))
+        p.parent.mkdir(exist_ok=True, parents=True)
 
-        while True:
-            p = self.cfg.path / path / (name + suffix)
-            p.parent.mkdir(exist_ok=True, parents=True)
+        for i in itertools.count():
+            f = p.parent / (p.name + bool(i) * f'_{i}')
             try:
-                return self.open(p, metadata)
+                return self.open(f, metadata)
             except FileExistsError:
-                index += 1
-                suffix = f'_{index}'
+                pass

recs-0.3.0/recs/base/_query_device.py

@@ -0,0 +1,21 @@
+"""
+Print the current devices as JSON without loading any other part of recs.
+
+Called repeatedly as a subprocess to detect devices going off- and online.
+"""
+
+import json
+import typing as t
+
+
+def query_devices() -> list[dict[str, t.Any]]:
+    try:
+        import sounddevice
+
+        return sounddevice.query_devices()
+    except Exception:
+        return []
+
+
+if __name__ == '__main__':
+    print(json.dumps(query_devices(), indent=4))

{recs-0.2.0 → recs-0.3.0}/recs/base/cfg_raw.py

@@ -11,15 +11,15 @@ class CfgRaw:
     #
     # Directory settings
     #
-    path: Path = Path()
-    subdirectory: t.Sequence[str] = ()
+    path: str = ''
     #
     # General purpose settings
     #
+    calibrate: bool = False
     dry_run: bool = False
+    verbose: bool = False
     info: bool = False
     list_types: bool = False
-    verbose: bool = False
     #
     # Aliases for input devices or channels
     #
@@ -40,19 +40,21 @@ class CfgRaw:
     #
     # Console and UI settings
     #
+    clear: bool = False
     silent: bool = False
-    retain: bool = True
-    ui_refresh_rate: float = 23
-    sleep_time: float = 0.013
+    sleep_time_device: float = 0.1
+    ui_refresh_rate: float = 23.0
     #
     # Settings relating to times
     #
     infinite_length: bool = False
-    longest_file_time: str = '0'  # In HH:MM:SS.SSSS
-    moving_average_time: float = 1
-    noise_floor: float = 70
-    shortest_file_time: str = '1'  # In HH:MM:SS.SSSS
-    quiet_after_end: float = 2
-    quiet_before_start: float = 1
-    stop_after_quiet: float = 20
-    total_run_time: float = 0
+    longest_file_time: float = 0.0
+    moving_average_time: float = 1.0
+    noise_floor: float = 70.0
+    shortest_file_time: float = 1.0
+    quiet_after_end: float = 2.0
+    quiet_before_start: float = 1.0
+    stop_after_quiet: float = 20.0
+    total_run_time: float = 0.0
+
+    asdict = dc.asdict

recs-0.3.0/recs/base/prefix_dict.py

@@ -0,0 +1,26 @@
+import typing as t
+
+T = t.TypeVar('T')
+
+
+class PrefixDict(dict[str, T]):
+    def __getitem__(self, key: str) -> T:
+        try:
+            return super().__getitem__(key)
+        except KeyError:
+            pass
+
+        error = 'unknown'
+        if key := key.strip().lower():
+            try:
+                return super().__getitem__(key)
+            except KeyError:
+                pass
+
+            matches = [v for k, v in self.items() if k.lower().startswith(key)]
+            if len(matches) == 1:
+                return matches[0]
+            if matches:
+                error = 'ambiguous'
+
+        raise KeyError(key, error)