Metadata-Version: 2.5
Name: evoid-jitsi-maubot
Version: 0.2.1
Summary: EVOID adapter for maubot — Jitsi Meet management via Matrix commands with EVOID pipeline
Project-URL: Homepage, https://github.com/EvolveBeyond/evoid-plugins
Project-URL: Documentation, https://evolvebeyond.github.io/EVOID/
Project-URL: Repository, https://github.com/EvolveBeyond/evoid-plugins
Author-email: EvolveBeyond <pakrohk@gmail.com>
License: Apache-2.0
Keywords: evoid,iop,jitsi,matrix,maubot,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.12
Requires-Dist: evoid>=0.6.9
Requires-Dist: maubot>=0.6.0
Requires-Dist: mautrix>=0.18.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: evoid-di>=0.1.0; extra == 'full'
Requires-Dist: evoid-smart-storage>=0.1.0; extra == 'full'
Requires-Dist: evoid-sqlite>=0.1.0; extra == 'full'
Provides-Extra: storage
Requires-Dist: evoid-di>=0.1.0; extra == 'storage'
Requires-Dist: evoid-smart-storage>=0.1.0; extra == 'storage'
Requires-Dist: evoid-sqlite>=0.1.0; extra == 'storage'
Description-Content-Type: text/markdown

# evoid-maubot

EVOID adapter for [maubot](https://github.com/maubot/maubot) — bridges Matrix events to Jitsi iframe commands via EVOID pipeline.

## What It Does

Converts Matrix `!jitsi` commands into EVOID Intents, which map to Jitsi's 50+ iframe API commands. Full reference: https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-iframe-commands/

## Installation

```bash
# As EVOID plugin
evo plug install evoid-maubot

# As maubot plugin
cd packages/evoid-maubot
zip -9r evoid-maubot.mbp *
# Upload .mbp to maubot management interface
```

## Commands

### Room Management
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi create [name]` | Create a new meeting | |
| `!jitsi join <room>` | Get join link | |
| `!jitsi hangup` | End the call | |
| `!jitsi end` | End conference for everyone | Yes |

### Watch Party
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi watch <url> [name]` | Create watch party (YouTube/video/audio) | |
| `!jitsi stopwatch` | Stop shared video | |

### Display
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi name <name>` | Set display name | |
| `!jitsi email <email>` | Set email address | |
| `!jitsi subject <text>` | Set conference subject | Yes |
| `!jitsi localsubject <text>` | Set local subject | |

### Media Control
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi mute` | Toggle audio mute | |
| `!jitsi video` | Toggle video mute | |
| `!jitsi screen` | Toggle screen sharing | |
| `!jitsi muteall [audio|video]` | Mute all participants | Yes |
| `!jitsi muteremote <id> [audio|video]` | Mute specific participant | Yes |
| `!jitsi noise [true|false]` | Toggle noise suppression | |
| `!jitsi quality <720|480|360|240>` | Set video quality | |
| `!jitsi audioonly [true|false]` | Audio only mode | |
| `!jitsi camera [user|environment]` | Toggle camera facing | |
| `!jitsi mirror` | Toggle camera mirror | |
| `!jitsi vbg` | Toggle virtual background dialog | |
| `!jitsi blur [slight-blur|blur|none]` | Set blurred background | |
| `!jitsi virtualbg [true|false] [img]` | Set virtual background | |

### Layout
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi tile` | Toggle tile view | |
| `!jitsi settile [true|false]` | Set tile view | |
| `!jitsi filmstrip` | Toggle filmstrip | |
| `!jitsi chat` | Toggle chat panel | |
| `!jitsi hand` | Toggle raise hand | |
| `!jitsi subtitles` | Toggle subtitles | |
| `!jitsi setsubtitles [true|false] [lang]` | Set subtitles | |
| `!jitsi participants [true|false]` | Toggle participants pane | |
| `!jitsi whiteboard` | Toggle whiteboard | |
| `!jitsi lobby [true|false]` | Toggle lobby mode | Yes |

### Participants
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi kick <id>` | Kick participant | Yes |
| `!jitsi mod <id>` | Grant moderator | Yes |
| `!jitsi pin [id]` | Pin participant | |
| `!jitsi volume <id> <0-1>` | Set volume | |
| `!jitsi largevideo [id] [camera|desktop]` | Set large video | |
| `!jitsi names <id:name> [id:name ...]` | Overwrite names locally | |
| `!jitsi sendto <id> <roomId>` | Send to breakout room | Yes |

### Moderation
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi approveknock <id> <true|false>` | Approve/reject lobby participant | Yes |
| `!jitsi moderation <true|false> <audio|video>` | Toggle moderation | Yes |
| `!jitsi askunmute <id>` | Ask to unmute | Yes |
| `!jitsi approvevideo <id>` | Approve participant for video | Yes |
| `!jitsi reject <id> <audio|video>` | Reject participant | Yes |

### Chat
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi send <message> [id]` | Send chat message | |
| `!jitsi pm <id>` | Start private chat | |
| `!jitsi cancelpm` | Cancel private chat | |
| `!jitsi notify <title> [desc]` | Show notification | |
| `!jitsi hidenotify <uid>` | Hide notification | |
| `!jitsi tone <tones> [dur] [pause]` | Play touch tones | |

### Recording
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi record <local|file|stream> [key]` | Start recording | Yes |
| `!jitsi stoprecord <local|file|stream>` | Stop recording | Yes |

### Breakout Rooms
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi breakout [name]` | Create breakout room | Yes |
| `!jitsi autobreakout` | Auto-assign participants | Yes |
| `!jitsi closebreakout <roomId>` | Close breakout room | Yes |
| `!jitsi joinbreakout [roomId]` | Join a breakout room | |
| `!jitsi removebreakout <jid>` | Remove breakout room | Yes |

### Misc
| Command | Description | Mod |
|---------|-------------|-----|
| `!jitsi followme [true|false] [recorderOnly]` | Toggle follow me | Yes |
| `!jitsi config <key=value> ...` | Overwrite config | Yes |
| `!jitsi bandwidth <bps>` | Set assumed bandwidth | |
| `!jitsi timer [duration] [elapsed]` | Set meeting timer | |
| `!jitsi resizefilm <width>` | Resize filmstrip width | |
| `!jitsi resizelarge <w> <h>` | Resize large video | |
| `!jitsi sendcamera <id> [user|env]` | Request camera change | |
| `!jitsi sendtext <id> <text>` | Send private text | |

## Configuration

```yaml
# base-config.yaml
service_name: maubot-bot
command_prefix: jitsi

jitsi:
  server_url: https://meet.example.com
  muc_domain: conference.meet.example.com
  admin_username: admin
  admin_password: secret

admin_whitelist:
  - "@admin:example.com"

storage:
  db_path: jitsi-bot.db
  enable_smart_routing: true

debug: false
```

### Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `service_name` | `maubot-bot` | EVOID service name for intent routing |
| `command_prefix` | `jitsi` | Matrix command prefix (without `!`) |
| `jitsi.server_url` | (empty) | Base URL of your Jitsi Meet instance |
| `jitsi.muc_domain` | (empty) | MUC conference domain |
| `jitsi.admin_username` | (empty) | Admin username for server-side ops |
| `jitsi.admin_password` | (empty) | Admin password for server-side ops |
| `admin_whitelist` | `[]` | Matrix user IDs allowed for moderator commands |
| `storage.db_path` | `jitsi-bot.db` | SQLite database file path |
| `storage.enable_smart_routing` | `true` | Enable smart storage routing |
| `debug` | `false` | Enable debug logging |

## Storage

Optional persistence via `evoid-sqlite` and `evoid-smart-storage`:

```bash
pip install evoid-maubot[storage]
```

Data stored:

| Type | Namespace | Content |
|------|-----------|---------|
| `meeting:*` | meetings | Room ID, name, creator, URL |
| `watch:*` | watch_parties | Video URL, content type, creator |
| `mod:*` | moderators | Moderator grants |

Storage is optional — bot works without it but won't persist data across restarts.

## EVOID Integration

Each command maps to a Jitsi iframe API command. The flow:

```
!jitsi watch https://youtube.com/watch?v=abc
    ↓
Matrix Event → Adapter → Intent(name="jitsi:watch", level=STANDARD)
    ↓
Pipeline: validate → authorize
    ↓
Handler returns: {iframe_command: "startShareVideo", args: {url: "..."}}
    ↓
Jitsi executes command in user's browser
```

Moderator commands use `level=CRITICAL` for full pipeline (validate → authorize → audit → protect).

The plugin uses `evoid.native.on` to register intents with the EVOID message bus. Intents are published via `evoid.publish` and routed through the IOP pipeline.

## Development

```bash
uv venv && uv pip install -e ".[dev]"
ruff check evoid_maubot/
ruff format evoid_maubot/
pytest tests/ -v
```

## License

Apache-2.0