cinny-desktop/docs/API-QUICKSTART.md

Paarrot API Quick Start

A local HTTP API server for controlling Paarrot from external devices like Stream Deck, scripts, and automation tools.

🚀 Getting Started

The API server starts automatically when you run Paarrot. It listens on http://127.0.0.1:33384.

Test the API

Option 1: Using Postman

Import the Postman collection for easy testing:

1. Open Postman
2. Click Import → File
3. Select paarrot-api.postman_collection.json
4. All endpoints will be ready to use!

The collection is automatically updated on git push.

Option 2: Using the test script

node test-api.js

Option 3: Using curl

./test-api.sh

Option 4: Manual curl commands

# Health check
curl http://127.0.0.1:33384/health

# Toggle mute
curl -X POST http://127.0.0.1:33384/mute/toggle

# Send message
curl -X POST http://127.0.0.1:33384/message/current \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from API!"}'

📝 Quick Reference

Common Endpoints

Endpoint	Method	Description
/health	GET	Check if API is running
/status	GET	Get app status (mute, deafen, etc.)
/mute/toggle	POST	Toggle microphone mute
/deafen/toggle	POST	Toggle deafen
/channels	GET	Get list of rooms
/channel	POST	Switch to a room
/message/current	POST	Send message to current room

🎮 Stream Deck Integration

1. Install the "API Ninja" or "HTTP Request" plugin
2. Create buttons with these settings:

Mute Toggle Button:

• URL: http://127.0.0.1:33384/mute/toggle
• Method: POST

Quick Message Button:

• URL: http://127.0.0.1:33384/message/current
• Method: POST
• Body: {"message": "BRB!"}

🔧 Integration with Paarrot

To enable full functionality, you need to implement the action handlers in the Cinny frontend:

1. Import the API handler in your app initialization:

import { initPaarrotAPI } from './app/paarrot-api';

// After Matrix client is initialized
initPaarrotAPI(matrixClient);

2. Implement the TODO items in cinny/src/app/paarrot-api.ts:
   • Mute/unmute logic (WebRTC audio)
   • Deafen logic (WebRTC audio output)
   • Navigation to rooms (router integration)
   • Get current room from URL/state

📖 Full Documentation

See API.md for complete API documentation including:

• All available endpoints
• Request/response formats
• Error handling
• Code examples in multiple languages
• Detailed integration guide

🛠️ Configuration

Edit electron/api-server.js to customize:

• Port number (default: 33384)
• Timeout duration (default: 10s)
• CORS settings

🐛 Troubleshooting

API not responding:

1. Check if Paarrot is running
2. Look for "Paarrot API server listening" in console logs
3. Verify port 33384 is not in use: lsof -i :33384

Actions not working:

1. Check browser console for errors
2. Ensure initPaarrotAPI() is called in your app
3. Implement the TODO items in paarrot-api.ts

Port in use: Edit electron/api-server.js and change the port number in the constructor.

📦 Files

• electron/api-server.js - API server implementation
• cinny/src/app/paarrot-api.ts - Client-side handler (needs implementation)
• test-api.js - Node.js test script
• test-api.sh - Bash test script
• API.md - Full documentation

🔐 Security

• API only listens on localhost (127.0.0.1)
• Not accessible from network
• No authentication required (local only)
• CORS enabled for all origins (safe since localhost only)

💡 Examples

Python Script:

import requests

def toggle_mute():
    r = requests.post('http://127.0.0.1:33384/mute/toggle')
    print(r.json())

toggle_mute()

JavaScript:

async function sendQuickMessage(msg) {
  const res = await fetch('http://127.0.0.1:33384/message/current', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: msg })
  });
  return res.json();
}

🎯 Next Steps

1. Run Paarrot: npm run dev
2. Test the API: node test-api.js
3. Integrate the handler: Import and call initPaarrotAPI()
4. Implement the TODO items in paarrot-api.ts
5. Create Stream Deck buttons or automation scripts!

---

For more details, see API.md