msw-open-ephys 3.1.0__tar.gz

msw_open_ephys-3.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+src/*/_version.py

msw_open_ephys-3.1.0/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+
+Permission is granted, free of charge, to use, copy, modify, and distribute
+this software and associated documentation files (the "Software") for
+non-commercial research or academic purposes only, subject to the following
+conditions:
+
+1. This copyright notice and permission notice must be included in all copies
+   or substantial portions of the Software.
+
+2. Any publication, presentation, or product that uses or builds upon the
+   Software must give clear attribution to the original work and its authors.
+
+3. Commercial use is prohibited without a separate written commercial licence
+   agreement with the copyright holder. Commercial use means incorporation of
+   the Software into anything for which fees or other compensation are charged
+   or received, including commercial products and commercial services.
+
+4. No patent licence, express or implied, is granted under these terms. Any
+   use that would require a patent licence from the copyright holder requires
+   a separate written agreement.
+
+5. Redistribution, in source or binary form, is permitted only for
+   non-commercial purposes and must retain this notice unmodified.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
+
+For commercial or patent licensing enquiries contact: lars@rollik.me

msw_open_ephys-3.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: msw-open-ephys
+Version: 3.1.0
+Summary: Remote control for Open Ephys GUI v1+ — session naming and recording management
+Project-URL: Homepage, https://github.com/murineshiftwork/msw-open-ephys
+Project-URL: Issue Tracker, https://github.com/murineshiftwork/msw-open-ephys/issues
+Author-email: "Lars B. Rollik" <lars@rollik.me>
+License: Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+        
+        Permission is granted, free of charge, to use, copy, modify, and distribute
+        this software and associated documentation files (the "Software") for
+        non-commercial research or academic purposes only, subject to the following
+        conditions:
+        
+        1. This copyright notice and permission notice must be included in all copies
+           or substantial portions of the Software.
+        
+        2. Any publication, presentation, or product that uses or builds upon the
+           Software must give clear attribution to the original work and its authors.
+        
+        3. Commercial use is prohibited without a separate written commercial licence
+           agreement with the copyright holder. Commercial use means incorporation of
+           the Software into anything for which fees or other compensation are charged
+           or received, including commercial products and commercial services.
+        
+        4. No patent licence, express or implied, is granted under these terms. Any
+           use that would require a patent licence from the copyright holder requires
+           a separate written agreement.
+        
+        5. Redistribution, in source or binary form, is permitted only for
+           non-commercial purposes and must retain this notice unmodified.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+        DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+        SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
+        
+        For commercial or patent licensing enquiries contact: lars@rollik.me
+License-File: LICENSE
+Keywords: electrophysiology,neuroscience,open-ephys,recording,remote-control
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Free for non-commercial use
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: msw-plugin-api>=0.1.0
+Requires-Dist: requests
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: commitizen; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# msw-open-ephys
+
+Remote control for [Open Ephys GUI](https://open-ephys.org/gui) v1+ — session naming, recording management, and metadata writing for MSW acquisition workflows.
+
+## Install
+
+```bash
+pip install msw-open-ephys
+```
+
+Or editable from the repo:
+
+```bash
+pip install -e external/msw-open-ephys
+```
+
+## CLI
+
+```
+oe-remote status   --remote-ip 172.24.242.168
+oe-remote preview  --remote-ip 172.24.242.168
+oe-remote record   --remote-ip 172.24.242.168 --subject m1099 \
+                   --acquisition-extension ephys_multi_behavior \
+                   --session-extension pxi
+oe-remote record   --remote-ip 172.24.242.168 --subject m1099 \
+                   --session-extension intan_ttl --child @last
+oe-remote stop     --remote-ip 172.24.242.168
+```
+
+### Session modes
+
+| Mode | When | OE records to |
+|---|---|---|
+| Standalone | no `--acquisition-extension`, no `--child` | `remote/{subject}/{subject__dt__session}/` |
+| Parent | `--acquisition-extension` set | `remote/{subject}/{subject__dt__acq}/{subject__dt__session}/` |
+| Child | `--child ACQ_PATH` or `--child @last` | `remote/{acq_path}/{subject__dt__session}/` |
+
+`--child @last` reuses the acquisition path cached by the most recent parent or record command.
+
+## Python API
+
+```python
+from msw_open_ephys.controller import OEController
+from msw_open_ephys.session import Session
+
+oe = OEController(ip="172.24.242.168")
+oe.preview()
+oe.configure_recording(parent_directory=r"E:\OE_DATA", base_text="m1099/acq/session")
+oe.record()
+```
+
+## Integration with MSW
+
+`msw run --parent openephys` calls the OE REST API directly via `murineshiftwork.hardware.parent_session` (uses `open-ephys-python-tools`, not this package). This package provides the **`oe-remote` CLI** used to start the acquisition side before launching MSW tasks.
+
+Set `open_ephys_url` in the setup YAML so MSW can attach automatically:
+
+```yaml
+# msw_configs/setups/setup-npxb.yaml
+open_ephys_url: 172.24.242.168
+```

msw_open_ephys-3.1.0/README.md

@@ -0,0 +1,61 @@
+# msw-open-ephys
+
+Remote control for [Open Ephys GUI](https://open-ephys.org/gui) v1+ — session naming, recording management, and metadata writing for MSW acquisition workflows.
+
+## Install
+
+```bash
+pip install msw-open-ephys
+```
+
+Or editable from the repo:
+
+```bash
+pip install -e external/msw-open-ephys
+```
+
+## CLI
+
+```
+oe-remote status   --remote-ip 172.24.242.168
+oe-remote preview  --remote-ip 172.24.242.168
+oe-remote record   --remote-ip 172.24.242.168 --subject m1099 \
+                   --acquisition-extension ephys_multi_behavior \
+                   --session-extension pxi
+oe-remote record   --remote-ip 172.24.242.168 --subject m1099 \
+                   --session-extension intan_ttl --child @last
+oe-remote stop     --remote-ip 172.24.242.168
+```
+
+### Session modes
+
+| Mode | When | OE records to |
+|---|---|---|
+| Standalone | no `--acquisition-extension`, no `--child` | `remote/{subject}/{subject__dt__session}/` |
+| Parent | `--acquisition-extension` set | `remote/{subject}/{subject__dt__acq}/{subject__dt__session}/` |
+| Child | `--child ACQ_PATH` or `--child @last` | `remote/{acq_path}/{subject__dt__session}/` |
+
+`--child @last` reuses the acquisition path cached by the most recent parent or record command.
+
+## Python API
+
+```python
+from msw_open_ephys.controller import OEController
+from msw_open_ephys.session import Session
+
+oe = OEController(ip="172.24.242.168")
+oe.preview()
+oe.configure_recording(parent_directory=r"E:\OE_DATA", base_text="m1099/acq/session")
+oe.record()
+```
+
+## Integration with MSW
+
+`msw run --parent openephys` calls the OE REST API directly via `murineshiftwork.hardware.parent_session` (uses `open-ephys-python-tools`, not this package). This package provides the **`oe-remote` CLI** used to start the acquisition side before launching MSW tasks.
+
+Set `open_ephys_url` in the setup YAML so MSW can attach automatically:
+
+```yaml
+# msw_configs/setups/setup-npxb.yaml
+open_ephys_url: 172.24.242.168
+```

msw_open_ephys-3.1.0/VERSION

@@ -0,0 +1 @@
+3.1.0

msw_open_ephys-3.1.0/pyproject.toml

@@ -0,0 +1,135 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "msw-open-ephys"
+dynamic = ["version"]
+authors = [
+    { name = "Lars B. Rollik", email = "lars@rollik.me" }
+]
+description = "Remote control for Open Ephys GUI v1+ — session naming and recording management"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+keywords = [
+    "open-ephys", "neuroscience", "electrophysiology", "recording", "remote-control",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: Free for non-commercial use",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "requests",
+    "rich",
+    "msw-plugin-api>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "commitizen",
+    "pytest>=8",
+    "pytest-cov",
+    "pre-commit",
+    "ruff",
+    "mypy",
+]
+docs = [
+    "mkdocs-material",
+]
+
+[project.scripts]
+oe-remote = "msw_open_ephys:run_cli"
+
+[project.entry-points."msw.cli"]
+oe = "msw_open_ephys.cli:register"
+
+[project.entry-points."msw.host"]
+openephys = "msw_open_ephys.host:OpenEphysHostSession"
+
+[project.urls]
+Homepage = "https://github.com/murineshiftwork/msw-open-ephys"
+"Issue Tracker" = "https://github.com/murineshiftwork/msw-open-ephys/issues"
+
+# ---------------------------------------------------------------------------
+# Build
+# ---------------------------------------------------------------------------
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "3.0.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/msw_open_ephys/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/msw_open_ephys"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/msw_open_ephys",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+    "/VERSION",
+]
+
+# ---------------------------------------------------------------------------
+# Commitizen
+# ---------------------------------------------------------------------------
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "commitizen"
+version = "3.1.0"
+version_files = ["VERSION"]
+tag_format = "v$version"
+update_changelog_on_bump = false
+
+# ---------------------------------------------------------------------------
+# Pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=src/msw_open_ephys --cov-report=term-missing --maxfail=5"
+
+# ---------------------------------------------------------------------------
+# Ruff
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "PTH", "TCH", "PYI", "YTT", "N"]
+ignore = []
+fixable = ["ALL"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+# ---------------------------------------------------------------------------
+# Mypy
+# ---------------------------------------------------------------------------
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true

msw_open_ephys-3.1.0/src/msw_open_ephys/__init__.py

@@ -0,0 +1,20 @@
+import sys
+
+from msw_open_ephys.cli.parser import parse_args
+
+
+def run_cli(args=None):
+    """Entry point for the ``oe-remote`` CLI."""
+    if args is None:
+        args = sys.argv[1:]
+
+    if args and not isinstance(args[0], str):
+        args = list(args[0])
+
+    parsed = parse_args(args if args else ["-h"])
+
+    if "func" not in parsed:
+        return
+
+    func = parsed.pop("func")
+    func(**parsed)

msw_open_ephys-3.1.0/src/msw_open_ephys/__main__.py

@@ -0,0 +1,4 @@
+from msw_open_ephys import run_cli
+
+if __name__ == "__main__":
+    run_cli()

msw_open_ephys-3.1.0/src/msw_open_ephys/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '3.1.0'
+__version_tuple__ = version_tuple = (3, 1, 0)
+
+__commit_id__ = commit_id = None

msw_open_ephys-3.1.0/src/msw_open_ephys/cli/__init__.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any
+
+from msw_open_ephys.cli.commands import cmd_preview, cmd_record, cmd_status, cmd_stop
+from msw_open_ephys.cli.parser import (
+    _RECORD_DESCRIPTION,
+    _add_connection,
+    _add_metadata,
+)
+
+
+def register(subparsers: Any) -> None:
+    """Register the ``oe`` subcommand group with the MSW CLI.
+
+    Called automatically via the ``msw.cli`` entry-point group.
+    Adds: msw oe status | preview | record | stop
+    """
+    import argparse
+
+    class _Fmt(
+        argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter
+    ):
+        pass
+
+    oe = subparsers.add_parser(
+        "oe",
+        help="Open Ephys GUI remote control",
+        formatter_class=_Fmt,
+    )
+    sub = oe.add_subparsers(metavar="command", dest="oe_command")
+    sub.required = True
+
+    p = sub.add_parser(
+        "status",
+        formatter_class=_Fmt,
+        help="Print current GUI mode (IDLE / ACQUIRE / RECORD)",
+    )
+    _add_connection(p)
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser(
+        "preview",
+        formatter_class=_Fmt,
+        help="Start acquisition (ACQUIRE mode, no recording)",
+    )
+    _add_connection(p)
+    p.set_defaults(func=cmd_preview)
+
+    p = sub.add_parser(
+        "record",
+        formatter_class=_Fmt,
+        description=_RECORD_DESCRIPTION,
+        help="Configure paths and start recording",
+    )
+    _add_connection(p)
+    _add_metadata(p)
+    p.set_defaults(func=cmd_record)
+
+    p = sub.add_parser(
+        "stop", formatter_class=_Fmt, help="Stop acquisition / recording (IDLE mode)"
+    )
+    _add_connection(p)
+    p.set_defaults(func=cmd_stop)
+
+
+def run_cli() -> None:
+    from msw_open_ephys.cli.parser import parse_args
+
+    args = parse_args()
+    func = args.pop("func", None)
+    if func:
+        func(**args)

msw_open_ephys-3.1.0/src/msw_open_ephys/cli/commands.py

@@ -0,0 +1,119 @@
+import json
+import logging
+import time
+
+from rich import get_console
+from rich.logging import RichHandler
+
+from msw_open_ephys.controller import OEController
+from msw_open_ephys.session import Session
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+
+def setup_logging(debug: bool = False) -> None:
+    level = "DEBUG" if debug else "INFO"
+    logger = logging.getLogger()
+    if logger.handlers:
+        return
+    logger.setLevel(getattr(logging, level))
+    handler = RichHandler(
+        console=get_console(),
+        level=level,
+        enable_link_path=False,
+        markup=True,
+        rich_tracebacks=True,
+    )
+    handler.setFormatter(logging.Formatter("%(message)s", datefmt="%H:%M:%S"))
+    logger.addHandler(handler)
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_status(ip: str, port: int, debug: bool = False, **_) -> None:
+    setup_logging(debug)
+    oe = OEController(ip=ip, port=port)
+    logging.info(f"Open Ephys status: {oe.status}")
+
+
+def cmd_preview(ip: str, port: int, debug: bool = False, **_) -> None:
+    setup_logging(debug)
+    oe = OEController(ip=ip, port=port)
+    oe.preview()
+    logging.info(f"Open Ephys status: {oe.status}")
+
+
+def cmd_stop(ip: str, port: int, debug: bool = False, **_) -> None:
+    setup_logging(debug)
+    oe = OEController(ip=ip, port=port)
+    oe.stop()
+    logging.info(f"Open Ephys status: {oe.status}")
+
+
+def cmd_record(
+    ip: str,
+    port: int,
+    subject: str,
+    local_path: str,
+    remote_path: str,
+    session_extension: str,
+    acquisition_extension: str = "",
+    is_child_session_to: str = "",
+    debug: bool = False,
+    **_,
+) -> None:
+    setup_logging(debug)
+
+    is_child_session_to = Session.resolve_child(is_child_session_to)
+
+    session = Session(
+        subject=subject,
+        session_extension=session_extension,
+        acquisition_extension=acquisition_extension,
+        local_path=local_path,
+        remote_path=remote_path,
+        ip=ip,
+        port=port,
+        is_child_session_to=is_child_session_to,
+    )
+
+    logging.info(f"Session:      {session.session_name}")
+    if session.acquisition_extension:
+        logging.info(f"Acquisition:  {session.acquisition_name}")
+    logging.info(f"Records to:   {session.main_session_folder}")
+    logging.info(f"Local path:   {session.local_path_full}")
+    logging.debug(f"parent_directory: {session.parent_directory}")
+    logging.debug(f"base_text:        {session.base_text}")
+
+    oe = OEController(ip=ip, port=port)
+    oe.preview()
+
+    oe.configure_recording(session.parent_directory, session.base_text)
+    logging.debug(f"Recording confirmed: {oe.recording}")
+
+    time.sleep(1)
+    oe.record()
+    time.sleep(1)
+
+    if oe.status != OEController.MODE_RECORD:
+        logging.error("Open Ephys did not enter RECORD mode — aborting metadata write.")
+        return
+
+    # Create local directories and write metadata
+    session.local_path_full.mkdir(parents=True, exist_ok=True)
+    (session.local_path_full / session.session_name).mkdir(parents=True, exist_ok=True)
+
+    meta = session.metadata(oe_state=oe.recording)
+    with session.metadata_file.open("w") as f:
+        json.dump(meta, f, indent=4, sort_keys=True)
+    logging.info(f"Metadata:     {session.metadata_file}")
+
+    # Always cache so --child @last works after any record command
+    session.save_to_cache()
+    print("\nSESSION PATH (use with --child for further sessions):")
+    print(f"  {session._cache_path}\n")

msw_open_ephys-3.1.0/src/msw_open_ephys/cli/parser.py

@@ -0,0 +1,172 @@
+import argparse
+
+from msw_open_ephys.cli.commands import cmd_preview, cmd_record, cmd_status, cmd_stop
+
+
+class _Fmt(
+    argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter
+):
+    pass
+
+
+_DEFAULT_IP = "localhost"
+_DEFAULT_PORT = 37497
+_DEFAULT_LOCAL_PATH = "/mnt/fastdata/data"
+_DEFAULT_REMOTE_PATH = r"E:\\OE_DATA\\LBR\\"
+
+_RECORD_DESCRIPTION = """\
+Configure recording paths and start an Open Ephys recording.
+
+Three modes are selected automatically based on the arguments provided:
+
+  Standalone  (no --acquisition-extension, no --child)
+    Use when ephys is the only session and no children are expected.
+    Records to: {remote-path}/{subject}/{subject__dt__session-ext}/Record Node/
+
+      oe-remote record --subject mouse1 --session-extension pxi
+
+  Parent      (--acquisition-extension is set, no --child)
+    Use when starting a multi-modal acquisition that will contain multiple
+    sessions. Creates a named acquisition folder and records the first
+    session inside it. Caches the acquisition path for --child @last.
+    Records to: {remote-path}/{subject}/{subject__dt__acq-ext}/
+                {subject__dt__session-ext}/Record Node/
+
+      oe-remote record --subject mouse1 \\
+        --acquisition-extension ephys_multi_behavior \\
+        --session-extension pxi
+
+  Child       (--child <acq_path> or --child @last)
+    Use when adding a session to an already-started parent acquisition.
+    Pass the acquisition folder path explicitly or use @last to reuse the
+    most recently cached path.
+    Records to: {remote-path}/{acq_path}/{subject__dt__session-ext}/Record Node/
+
+      oe-remote record --subject mouse1 \\
+        --session-extension intan_ttl \\
+        --child @last
+"""
+
+
+def _add_connection(parser: argparse.ArgumentParser) -> None:
+    g = parser.add_argument_group("Connection")
+    g.add_argument(
+        "-ip",
+        "--remote-ip",
+        dest="ip",
+        default=_DEFAULT_IP,
+        help="Open Ephys GUI host IP",
+    )
+    g.add_argument(
+        "-port",
+        "--remote-port",
+        dest="port",
+        type=int,
+        default=_DEFAULT_PORT,
+        help="Open Ephys HTTP API port",
+    )
+    g.add_argument(
+        "-d",
+        "--debug",
+        dest="debug",
+        action="store_true",
+        default=False,
+        help="Enable debug logging",
+    )
+
+
+def _add_metadata(parser: argparse.ArgumentParser) -> None:
+    g = parser.add_argument_group("Metadata / paths")
+    g.add_argument(
+        "--local-path",
+        dest="local_path",
+        default=_DEFAULT_LOCAL_PATH,
+        help="Local base data directory",
+    )
+    g.add_argument(
+        "--remote-path",
+        dest="remote_path",
+        default=_DEFAULT_REMOTE_PATH,
+        help="Remote base data directory (as seen by Open Ephys GUI)",
+    )
+    g.add_argument(
+        "--subject",
+        dest="subject",
+        default="_test_oe_controller",
+        help="Subject identifier",
+    )
+    g.add_argument(
+        "--session-extension",
+        dest="session_extension",
+        required=True,
+        help="Session label appended to subject__datetime (e.g. pxi, intan_ttl)",
+    )
+    g.add_argument(
+        "--acquisition-extension",
+        dest="acquisition_extension",
+        default="",
+        help="Acquisition label for the parent folder (enables parent mode). "
+        "Example: ephys_multi_behavior",
+    )
+    g.add_argument(
+        "--child",
+        "--is-child-session-to",
+        dest="is_child_session_to",
+        default="",
+        metavar="ACQ_PATH",
+        help="Add this session under an existing acquisition folder. "
+        "Pass subject/acquisition_name or '@last' to use the most recently "
+        "cached path.",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="oe-remote",
+        description="Remote control for Open Ephys GUI v1+",
+        formatter_class=_Fmt,
+    )
+    sub = parser.add_subparsers(metavar="command", dest="command")
+    sub.required = True
+
+    # status
+    p = sub.add_parser(
+        "status",
+        formatter_class=_Fmt,
+        help="Print current GUI mode (IDLE / ACQUIRE / RECORD)",
+    )
+    _add_connection(p)
+    p.set_defaults(func=cmd_status)
+
+    # preview
+    p = sub.add_parser(
+        "preview",
+        formatter_class=_Fmt,
+        help="Start acquisition (ACQUIRE mode, no recording)",
+    )
+    _add_connection(p)
+    p.set_defaults(func=cmd_preview)
+
+    # record
+    p = sub.add_parser(
+        "record",
+        formatter_class=_Fmt,
+        description=_RECORD_DESCRIPTION,
+        help="Configure paths and start recording",
+    )
+    _add_connection(p)
+    _add_metadata(p)
+    p.set_defaults(func=cmd_record)
+
+    # stop
+    p = sub.add_parser(
+        "stop", formatter_class=_Fmt, help="Stop acquisition / recording (IDLE mode)"
+    )
+    _add_connection(p)
+    p.set_defaults(func=cmd_stop)
+
+    return parser
+
+
+def parse_args(args=None) -> dict:
+    return build_parser().parse_args(args).__dict__

msw_open_ephys-3.1.0/src/msw_open_ephys/controller.py

@@ -0,0 +1,103 @@
+import json
+import time
+
+import requests
+
+
+class OEController:
+    """HTTP controller for Open Ephys GUI v1+ (port 37497 by default).
+
+    Request format mirrors open_ephys.control.OpenEphysHTTPServer:
+    uses data=json.dumps(payload) rather than json=payload, which is
+    what the OE HTTP server expects.
+    """
+
+    MODE_IDLE = "IDLE"
+    MODE_ACQUIRE = "ACQUIRE"
+    MODE_RECORD = "RECORD"
+
+    def __init__(self, ip: str = "localhost", port: int = 37497):
+        self.ip = ip
+        self.port = port
+
+    @property
+    def _base(self) -> str:
+        return f"http://{self.ip}:{self.port}/api"
+
+    def _put(self, endpoint: str, payload: dict) -> dict:
+        r = requests.put(
+            self._base + endpoint,
+            data=json.dumps(payload),
+        )
+        r.raise_for_status()
+        return r.json()  # type: ignore[no-any-return]
+
+    def _get(self, endpoint: str) -> dict:
+        r = requests.get(self._base + endpoint)
+        r.raise_for_status()
+        return r.json()  # type: ignore[no-any-return]
+
+    # ------------------------------------------------------------------
+    # Mode control
+    # ------------------------------------------------------------------
+
+    @property
+    def status(self) -> str:
+        return str(self._get("/status")["mode"])
+
+    def preview(self) -> None:
+        self._put("/status", {"mode": self.MODE_ACQUIRE})
+
+    def stop(self) -> None:
+        self._put("/status", {"mode": self.MODE_IDLE})
+
+    # ------------------------------------------------------------------
+    # Recording configuration
+    # ------------------------------------------------------------------
+
+    @property
+    def recording(self) -> dict:
+        return self._get("/recording")
+
+    def configure_recording(self, parent_directory: str, base_text: str) -> None:
+        """Configure recording path on all Record Nodes.
+
+        parent_directory is set per Record Node (the only call that affects
+        nodes already in the signal chain). base_text carries the full
+        subdirectory hierarchy as a forward-slash path and is set globally.
+        OE creates all levels in base_text when recording starts.
+        """
+        # base_text and text fields are global settings
+        self._put(
+            "/recording",
+            {
+                "base_text": base_text,
+                "prepend_text": "",
+                "append_text": "",
+            },
+        )
+
+        # parent_directory must be set per node for existing Record Nodes
+        for node in self.recording.get("record_nodes", []):
+            self._put(
+                f"/recording/{node['node_id']}",
+                {"parent_directory": parent_directory},
+            )
+
+    # ------------------------------------------------------------------
+    # Record with sync wait
+    # ------------------------------------------------------------------
+
+    def _nodes_synchronized(self) -> bool:
+        for node in self.recording.get("record_nodes", []):
+            if not node.get("is_synchronized", False):
+                return False
+        return True
+
+    def record(self, poll_interval: float = 0.5) -> None:
+        while not self._nodes_synchronized():
+            print(
+                f"[{time.strftime('%H:%M:%S')}] Waiting for streams to synchronize..."
+            )
+            time.sleep(poll_interval)
+        self._put("/status", {"mode": self.MODE_RECORD})

msw_open_ephys-3.1.0/src/msw_open_ephys/host.py

@@ -0,0 +1,130 @@
+"""OpenEphysHostSession — MSW host-session plugin for Open Ephys GUI v1+.
+
+Registered under the ``msw.host`` entry-point group as ``openephys``.
+MSW discovers and instantiates this class via
+``make_host_session("openephys", url=...)``.
+
+The session is started externally via ``oe-remote record`` before ``msw run``.
+``attach()`` reads the current recording state from the OE HTTP API and returns
+the acquisition context.  ``start()`` and ``stop()`` are intentional no-ops —
+lifecycle control is handled by ``oe-remote``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from msw_plugin_api import HostSessionInfo
+
+log = logging.getLogger(__name__)
+
+_HOST_RE = re.compile(r"(?:https?://)?([^:/]+)")
+
+
+def _parse_host(url: str) -> str:
+    m = _HOST_RE.match(url.strip())
+    return m.group(1) if m else url
+
+
+class OpenEphysHostSession:
+    """Reads acquisition context from a running Open Ephys GUI process.
+
+    Expects ``base_text`` set by ``oe-remote record`` to be a 3-part path::
+
+        subject / acquisition_name / oe_session_name
+
+    Returns ``None`` from ``attach()`` when OE is unreachable or base_text
+    is not yet set by oe-remote.
+    """
+
+    name = "openephys"
+
+    def __init__(self, url: str = "localhost", require_recording: bool = False) -> None:
+        self._host = _parse_host(url)
+        self._require_recording = require_recording
+        self.fail_reason: str = ""
+
+    def attach(self, **kwargs: object) -> HostSessionInfo | None:
+        try:
+            from msw_open_ephys.controller import OEController
+        except ImportError:
+            self.fail_reason = (
+                "msw-open-ephys not installed (pip install msw-open-ephys)"
+            )
+            log.error("OpenEphys: %s", self.fail_reason)
+            return None
+
+        gui = OEController(ip=self._host)
+
+        try:
+            status = gui.status
+        except Exception as exc:
+            self.fail_reason = f"cannot reach {self._host} — {exc}"
+            log.error("OpenEphys: %s", self.fail_reason)
+            return None
+
+        if self._require_recording and status != "RECORD":
+            self.fail_reason = f"status={status!r} (not RECORD)"
+            log.info("OpenEphys: %s — no host session attached", self.fail_reason)
+            return None
+
+        try:
+            rec = gui.recording
+        except Exception as exc:
+            self.fail_reason = f"GET /api/recording failed — {exc}"
+            log.error("OpenEphys: %s", self.fail_reason)
+            return None
+
+        log.debug("OpenEphys /api/recording: %s", rec)
+
+        base = (rec.get("base_text") or "").strip("/")
+        parts = [p for p in base.split("/") if p]
+        log.debug("OpenEphys base_text=%r -> parts=%s", base, parts)
+
+        if len(parts) < 2:
+            self.fail_reason = (
+                f"base_text {base!r} has <2 parts — "
+                f"run oe-remote record before msw run, "
+                f"or use --link-to ACQUISITION_NAME"
+            )
+            log.error("OpenEphys: %s", self.fail_reason)
+            return None
+
+        acq_segment = parts[1]
+        try:
+            from murineshiftwork.namespace.paths import get_msw_builder
+
+            _b = get_msw_builder()
+            acquisition_name = _b.build_path(
+                "session", _b.extract_level_values("session", acq_segment)
+            )
+        except ImportError:
+            acquisition_name = acq_segment
+        except ValueError:
+            self.fail_reason = (
+                f"base_text segment {acq_segment!r} is not a valid MSW session name "
+                f"(full base_text: {base!r}) — check oe-remote naming convention"
+            )
+            log.error("OpenEphys: %s", self.fail_reason)
+            return None
+
+        record_nodes = rec.get("record_nodes") or []
+        parent_dir = record_nodes[0].get("parent_directory", "") if record_nodes else ""
+
+        return HostSessionInfo(
+            backend="openephys",
+            acquisition_name=acquisition_name,
+            subject=parts[0],
+            parent_directory=parent_dir,
+            extra={
+                "oe_session_name": parts[2] if len(parts) > 2 else "",
+                "status": status,
+            },
+        )
+
+    def start(self) -> None:
+        """No-op: OE recording is started via oe-remote record before msw run."""
+
+    def stop(self) -> None:
+        """No-op: OE recording lifecycle is managed by oe-remote."""

msw_open_ephys-3.1.0/src/msw_open_ephys/session.py

@@ -0,0 +1,172 @@
+"""Session path and metadata management for Open Ephys recordings.
+
+Three session modes, selected by arguments:
+
+  Standalone  (no --acquisition-extension, no --child)
+    OE records to:  {remote_path}/{subject__dt__session_ext}/Record Node/
+    Local metadata: {local_path}/{subject}/{subject__dt__session_ext}/
+
+  Parent      (--acquisition-extension is set, no --child)
+    OE records to:  {remote_path}/{subject__dt__acq_ext}/
+                    {subject__dt__session_ext}/Record Node/
+    Local metadata: {local_path}/{subject}/{subject__dt__acq_ext}/
+    Caches acquisition_name for --child @last.
+
+  Child       (--child <acq_name> or --child @last)
+    OE records to:  {remote_path}/{acq_name}/{subject__dt__session_ext}/Record Node/
+    Local metadata: {local_path}/{subject}/{acq_name}/
+
+Remote path design
+------------------
+The OE GUI only creates the final leaf of parent_directory (cannot create
+intermediate dirs). To work around this, remote_path is always used as
+parent_directory on the Record Node (it already exists), and the full
+subdirectory hierarchy is written into base_text using forward slashes.
+OE accepts forward-slash paths in base_text on Windows and creates all
+levels correctly.
+
+  parent_directory = remote_path          (always, set per Record Node)
+  base_text        = acq_name/session_name (set globally via /api/recording)
+
+The cache stores acquisition_name (no subject prefix) so --child @last
+maps directly to the base_text prefix for child sessions.
+"""
+
+import time
+from pathlib import Path
+
+from msw_open_ephys._version import __version__ as _pkg_version
+
+METADATA_VERSION: str = _pkg_version
+
+_SESSION_CACHE = Path.home() / ".cache" / "oe-remote" / "last_session"
+
+
+class Session:
+    """Encapsulates all naming, path, and metadata logic for one recording."""
+
+    def __init__(
+        self,
+        subject: str,
+        session_extension: str,
+        local_path: str,
+        remote_path: str,
+        ip: str,
+        port: int,
+        acquisition_extension: str = "",
+        is_child_session_to: str = "",
+    ):
+        self.subject = subject
+        self.session_extension = session_extension
+        self.acquisition_extension = acquisition_extension
+        self.local_path = Path(local_path)
+        self.remote_path = remote_path.rstrip("/\\")
+        self.ip = ip
+        self.port = port
+        self.is_child_session_to = is_child_session_to
+
+        self.dt = time.strftime("%Y%m%d_%H%M%S")
+        self.session_name = f"{subject}__{self.dt}__{session_extension}"
+        self.acquisition_name = (
+            f"{subject}__{self.dt}__{acquisition_extension}"
+            if acquisition_extension
+            else self.session_name
+        )
+
+        self._compute_paths()
+
+    def _compute_paths(self) -> None:
+        # parent_directory is always the top-level remote path (known to exist).
+        # base_text carries the full subdirectory hierarchy with forward slashes;
+        # OE creates all levels when recording starts.
+        self.parent_directory = self.remote_path
+
+        if self.is_child_session_to:
+            # Case 3 – child
+            self.local_path_full = (
+                self.local_path / self.subject / self.is_child_session_to
+            )
+            self.base_text = f"{self.is_child_session_to}/{self.session_name}"
+            self.main_session_folder = self.base_text
+            self._cache_path = self.is_child_session_to
+
+        elif self.acquisition_extension:
+            # Case 2 – parent
+            self.local_path_full = (
+                self.local_path / self.subject / self.acquisition_name
+            )
+            self.base_text = (
+                f"{self.subject}/{self.acquisition_name}/{self.session_name}"
+            )
+            self.main_session_folder = self.base_text
+            self._cache_path = self.acquisition_name
+
+        else:
+            # Case 1 – standalone
+            self.local_path_full = self.local_path / self.subject / self.session_name
+            self.base_text = f"{self.subject}/{self.session_name}"
+            self.main_session_folder = self.session_name
+            self._cache_path = self.session_name
+
+    @property
+    def metadata_file(self) -> Path:
+        return self.local_path_full / f"{self.session_name}.settings.ephys.json"
+
+    def metadata(self, oe_state: dict | None = None) -> dict:
+        """Full metadata dict for the .settings.ephys.json file.
+
+        All keys from metadata_version 2 are preserved for backward compatibility.
+        Branch on ``metadata_version`` to handle format differences.
+        """
+        return {
+            # --- Version ---
+            "metadata_version": METADATA_VERSION,
+            "version": METADATA_VERSION,  # legacy key (was 2)
+            # --- Identity ---
+            "subject": self.subject,
+            "datetime": self.dt,
+            "acquisition_extension": self.acquisition_extension,
+            "session_extension": self.session_extension,
+            "acquisition_name": self.acquisition_name,
+            "session_name": self.session_extension,  # legacy: stored extension string
+            "full_session_name": self.session_name,  # full subject__dt__ext string
+            "full_acquisition_name": self.main_session_folder,  # legacy alias
+            "main_session_folder": self.main_session_folder,
+            "acquisition_task_name": self.acquisition_extension,  # legacy alias
+            "is_child_session_to": self.is_child_session_to,
+            # --- Local paths ---
+            "local_path": str(self.local_path),
+            "local_path_full": str(self.local_path_full),
+            "metadata_file": str(self.metadata_file),
+            # --- Remote / OE recording settings ---
+            "remote_ip": self.ip,
+            "remote_port": self.port,
+            "remote_path": self.remote_path,
+            "parent_directory": self.parent_directory,
+            "base_text": self.base_text,
+            "prepend_text": "",
+            "append_text": "",
+            "create_new_dir": True,
+            # --- OE live state snapshot (populated after recording starts) ---
+            "oe_settings": oe_state or {},
+        }
+
+    # ------------------------------------------------------------------
+    # Session cache — always written so --child @last works after any record
+    # ------------------------------------------------------------------
+
+    def save_to_cache(self) -> None:
+        _SESSION_CACHE.parent.mkdir(parents=True, exist_ok=True)
+        _SESSION_CACHE.write_text(self._cache_path)
+
+    @staticmethod
+    def resolve_child(value: str) -> str:
+        """Expand '@last' to the cached path, or pass value through."""
+        if value != "@last":
+            return value
+        if not _SESSION_CACHE.exists():
+            raise FileNotFoundError(
+                "No cached session found. Run any 'record' command first, "
+                "or pass the acquisition name explicitly to --child."
+            )
+        return _SESSION_CACHE.read_text().strip()

msw_open_ephys-3.1.0/tests/test_smoke.py

@@ -0,0 +1,51 @@
+"""Smoke tests — verify package imports and basic structure."""
+
+from __future__ import annotations
+
+
+def test_controller_importable() -> None:
+    from msw_open_ephys.controller import OEController
+
+    oe = OEController(ip="localhost", port=37497)
+    assert oe._base == "http://localhost:37497/api"
+
+
+def test_session_importable() -> None:
+    from msw_open_ephys.session import Session
+
+    s = Session(
+        subject="m01",
+        session_extension="pxi",
+        local_path="/tmp/data",
+        remote_path="E:\\OE_DATA",
+        ip="localhost",
+        port=37497,
+    )
+    assert s.subject == "m01"
+    assert s.session_name.startswith("m01__")
+    assert s.session_name.endswith("__pxi")
+
+
+def test_host_session_importable() -> None:
+    from msw_plugin_api import HostSessionProtocol
+
+    from msw_open_ephys.host import OpenEphysHostSession
+
+    client = OpenEphysHostSession(url="localhost")
+    assert isinstance(client, HostSessionProtocol)
+    assert client.name == "openephys"
+
+
+def test_cli_register_callable() -> None:
+    from msw_open_ephys.cli import register
+
+    assert callable(register)
+
+
+def test_entry_points_declared() -> None:
+    from importlib.metadata import entry_points
+
+    host_eps = {ep.name for ep in entry_points(group="msw.host")}
+    cli_eps = {ep.name for ep in entry_points(group="msw.cli")}
+    assert "openephys" in host_eps
+    assert "oe" in cli_eps