0
# Discord RPC Client
1
2
Full-featured Discord RPC client with support for authentication, guild/channel operations, voice settings, event subscriptions, and advanced Discord integration. The Client and AioClient classes provide comprehensive access to Discord's RPC API beyond simple Rich Presence.
3
4
## Capabilities
5
6
### Synchronous RPC Client
7
8
The Client class provides full Discord RPC functionality with synchronous method calls.
9
10
```python { .api }
11
class Client(BaseClient):
12
def __init__(self, client_id: str, **kwargs):
13
"""
14
Initialize synchronous RPC client.
15
16
Parameters:
17
- client_id (str): Discord application client ID
18
- loop: Optional event loop
19
- handler: Optional error handler function
20
- pipe (int): Optional specific pipe number (0-9)
21
- connection_timeout (int): Connection timeout in seconds (default: 30)
22
- response_timeout (int): Response timeout in seconds (default: 10)
23
"""
24
```
25
26
```python { .api }
27
def start(self):
28
"""Start the client and perform handshake with Discord."""
29
```
30
31
```python { .api }
32
def read(self):
33
"""
34
Read output from Discord RPC.
35
36
Returns:
37
dict: RPC response data
38
"""
39
```
40
41
```python { .api }
42
def close(self):
43
"""Close the connection to Discord."""
44
```
45
46
### Authentication & Authorization
47
48
```python { .api }
49
def authorize(self, client_id: str, scopes: list):
50
"""
51
Request authorization for the application.
52
53
Parameters:
54
- client_id (str): Discord application client ID
55
- scopes (list): List of OAuth2 scopes to request
56
57
Returns:
58
dict: Authorization response with code
59
"""
60
```
61
62
```python { .api }
63
def authenticate(self, token: str):
64
"""
65
Authenticate with Discord using an access token.
66
67
Parameters:
68
- token (str): OAuth2 access token
69
70
Returns:
71
dict: Authentication response with user info
72
"""
73
```
74
75
### Activity Management
76
77
```python { .api }
78
def set_activity(self, pid: int = None, state: str = None, details: str = None,
79
start: int = None, end: int = None,
80
large_image: str = None, large_text: str = None,
81
small_image: str = None, small_text: str = None,
82
party_id: str = None, party_size: list = None,
83
join: str = None, spectate: str = None,
84
match: str = None, buttons: list = None,
85
instance: bool = True):
86
"""
87
Set Rich Presence activity with full RPC client features.
88
89
Parameters:
90
- All parameters same as Presence.update()
91
92
Returns:
93
dict: Discord RPC response
94
"""
95
```
96
97
```python { .api }
98
def clear_activity(self, pid: int = None):
99
"""
100
Clear current activity.
101
102
Parameters:
103
- pid (int): Process ID (default: current process)
104
105
Returns:
106
dict: Discord RPC response
107
"""
108
```
109
110
```python { .api }
111
def send_activity_join_invite(self, user_id: str):
112
"""
113
Send activity join invite to a user.
114
115
Parameters:
116
- user_id (str): Target user ID
117
118
Returns:
119
dict: Discord RPC response
120
"""
121
```
122
123
```python { .api }
124
def close_activity_request(self, user_id: str):
125
"""
126
Close activity request from a user.
127
128
Parameters:
129
- user_id (str): User ID to close request from
130
131
Returns:
132
dict: Discord RPC response
133
"""
134
```
135
136
### Guild & Channel Operations
137
138
```python { .api }
139
def get_guilds(self):
140
"""
141
Get user's guilds (servers).
142
143
Returns:
144
dict: List of guild objects
145
"""
146
```
147
148
```python { .api }
149
def get_guild(self, guild_id: str):
150
"""
151
Get specific guild information.
152
153
Parameters:
154
- guild_id (str): Guild (server) ID
155
156
Returns:
157
dict: Guild object with details
158
"""
159
```
160
161
```python { .api }
162
def get_channels(self, guild_id: str):
163
"""
164
Get channels in a guild.
165
166
Parameters:
167
- guild_id (str): Guild (server) ID
168
169
Returns:
170
dict: List of channel objects
171
"""
172
```
173
174
```python { .api }
175
def get_channel(self, channel_id: str):
176
"""
177
Get specific channel information.
178
179
Parameters:
180
- channel_id (str): Channel ID
181
182
Returns:
183
dict: Channel object with details
184
"""
185
```
186
187
```python { .api }
188
def select_voice_channel(self, channel_id: str):
189
"""
190
Select a voice channel for the user.
191
192
Parameters:
193
- channel_id (str): Voice channel ID
194
195
Returns:
196
dict: Discord RPC response
197
"""
198
```
199
200
```python { .api }
201
def get_selected_voice_channel(self):
202
"""
203
Get currently selected voice channel.
204
205
Returns:
206
dict: Voice channel object or null
207
"""
208
```
209
210
```python { .api }
211
def select_text_channel(self, channel_id: str):
212
"""
213
Select a text channel for the user.
214
215
Parameters:
216
- channel_id (str): Text channel ID
217
218
Returns:
219
dict: Discord RPC response
220
"""
221
```
222
223
### Voice Settings
224
225
```python { .api }
226
def get_voice_settings(self):
227
"""
228
Get current voice settings.
229
230
Returns:
231
dict: Voice settings object
232
"""
233
```
234
235
```python { .api }
236
def set_voice_settings(self, _input: dict = None, output: dict = None,
237
mode: dict = None, automatic_gain_control: bool = None,
238
echo_cancellation: bool = None, noise_suppression: bool = None,
239
qos: bool = None, silence_warning: bool = None,
240
deaf: bool = None, mute: bool = None):
241
"""
242
Set voice settings.
243
244
Parameters:
245
- _input (dict): Input device settings
246
- output (dict): Output device settings
247
- mode (dict): Voice mode settings
248
- automatic_gain_control (bool): AGC enabled
249
- echo_cancellation (bool): Echo cancellation enabled
250
- noise_suppression (bool): Noise suppression enabled
251
- qos (bool): Quality of service enabled
252
- silence_warning (bool): Silence warning enabled
253
- deaf (bool): Deafened state
254
- mute (bool): Muted state
255
256
Returns:
257
dict: Discord RPC response
258
"""
259
```
260
261
```python { .api }
262
def set_user_voice_settings(self, user_id: str, pan_left: float = None,
263
pan_right: float = None, volume: int = None,
264
mute: bool = None):
265
"""
266
Set voice settings for a specific user.
267
268
Parameters:
269
- user_id (str): Target user ID
270
- pan_left (float): Left audio pan (-1.0 to 1.0)
271
- pan_right (float): Right audio pan (-1.0 to 1.0)
272
- volume (int): Volume level (0 to 200)
273
- mute (bool): User mute state
274
275
Returns:
276
dict: Discord RPC response
277
"""
278
```
279
280
### Event Management
281
282
```python { .api }
283
def register_event(self, event: str, func: callable, args: dict = None):
284
"""
285
Register an event handler function.
286
287
Parameters:
288
- event (str): Event name to listen for
289
- func (callable): Function to call when event occurs (must accept 1 parameter)
290
- args (dict): Additional arguments for subscription
291
292
Raises:
293
- ArgumentError: Function doesn't accept exactly 1 argument
294
- NotImplementedError: Function is a coroutine (use AioClient)
295
"""
296
```
297
298
```python { .api }
299
def unregister_event(self, event: str, args: dict = None):
300
"""
301
Unregister an event handler.
302
303
Parameters:
304
- event (str): Event name to stop listening for
305
- args (dict): Additional arguments for unsubscription
306
307
Raises:
308
- EventNotFound: Event was not registered
309
"""
310
```
311
312
```python { .api }
313
def subscribe(self, event: str, args: dict = None):
314
"""
315
Subscribe to Discord events.
316
317
Parameters:
318
- event (str): Event name
319
- args (dict): Event-specific arguments
320
321
Returns:
322
dict: Discord RPC response
323
"""
324
```
325
326
```python { .api }
327
def unsubscribe(self, event: str, args: dict = None):
328
"""
329
Unsubscribe from Discord events.
330
331
Parameters:
332
- event (str): Event name
333
- args (dict): Event-specific arguments
334
335
Returns:
336
dict: Discord RPC response
337
"""
338
```
339
340
### Utility Functions
341
342
```python { .api }
343
def capture_shortcut(self, action: str):
344
"""
345
Capture keyboard shortcut.
346
347
Parameters:
348
- action (str): Action to capture shortcut for
349
350
Returns:
351
dict: Discord RPC response
352
"""
353
```
354
355
### Asynchronous RPC Client
356
357
The AioClient class provides the same functionality as Client but with async/await support.
358
359
```python { .api }
360
class AioClient(BaseClient):
361
def __init__(self, client_id: str, **kwargs):
362
"""Initialize asynchronous RPC client with same parameters as Client."""
363
```
364
365
All methods from Client are available with async/await:
366
367
```python { .api }
368
async def start(self): ...
369
async def authorize(self, client_id: str, scopes: list): ...
370
async def authenticate(self, token: str): ...
371
async def set_activity(self, **kwargs): ...
372
async def get_guilds(self): ...
373
async def get_voice_settings(self): ...
374
async def register_event(self, event: str, func: callable, args: dict = None): ...
375
async def unregister_event(self, event: str, args: dict = None): ...
376
# ... all other methods as async
377
```
378
379
Note: Event handler functions for AioClient must be coroutines (async functions).
380
381
## Usage Examples
382
383
### Basic RPC Client
384
385
```python
386
from pypresence import Client
387
388
# Initialize and start
389
client = Client("your_client_id")
390
client.start()
391
392
# Set activity
393
response = client.set_activity(
394
state="In Competitive Match",
395
details="Ranked Game - Map: Dust II",
396
large_image="game_icon",
397
party_size=[2, 5]
398
)
399
400
# Get user's guilds
401
guilds = client.get_guilds()
402
print(f"User is in {len(guilds['data']['guilds'])} servers")
403
404
client.close()
405
```
406
407
### Authentication Flow
408
409
```python
410
from pypresence import Client
411
412
client = Client("your_client_id")
413
client.start()
414
415
# Request authorization
416
auth_response = client.authorize("your_client_id", ["rpc", "identify"])
417
print(f"Visit: {auth_response['data']['code']}")
418
419
# After user authorizes, authenticate with token
420
token = "your_oauth_token" # Get this from OAuth flow
421
user_info = client.authenticate(token)
422
print(f"Authenticated as: {user_info['data']['user']['username']}")
423
424
client.close()
425
```
426
427
### Event Handling
428
429
```python
430
from pypresence import Client
431
import time
432
433
def on_activity_join(data):
434
print(f"Someone wants to join: {data}")
435
# Handle join request
436
437
def on_activity_spectate(data):
438
print(f"Someone wants to spectate: {data}")
439
# Handle spectate request
440
441
client = Client("your_client_id")
442
client.start()
443
444
# Register event handlers
445
client.register_event("ACTIVITY_JOIN", on_activity_join)
446
client.register_event("ACTIVITY_SPECTATE", on_activity_spectate)
447
448
# Set activity with join/spectate secrets
449
client.set_activity(
450
state="In Game",
451
details="Accepting challenges",
452
join="join_secret_123",
453
spectate="spectate_secret_456"
454
)
455
456
# Keep alive to receive events
457
try:
458
while True:
459
time.sleep(1)
460
except KeyboardInterrupt:
461
client.close()
462
```
463
464
### Async RPC Client
465
466
```python
467
import asyncio
468
from pypresence import AioClient
469
470
async def on_ready(data):
471
print(f"Discord ready: {data}")
472
473
async def main():
474
client = AioClient("your_client_id")
475
await client.start()
476
477
# Register async event handler
478
await client.register_event("READY", on_ready)
479
480
# Get voice settings
481
voice_settings = await client.get_voice_settings()
482
print(f"Current volume: {voice_settings['data']['volume']}")
483
484
# Update voice settings
485
await client.set_voice_settings(volume=75, mute=False)
486
487
# Set activity
488
await client.set_activity(
489
state="Streaming",
490
details="Live coding session",
491
large_image="streaming_icon"
492
)
493
494
# Keep alive
495
await asyncio.sleep(60)
496
client.close()
497
498
asyncio.run(main())
499
```
500
501
### Voice Channel Management
502
503
```python
504
from pypresence import Client
505
506
client = Client("your_client_id")
507
client.start()
508
509
# Authenticate first (required for channel operations)
510
client.authenticate("your_token")
511
512
# Get user's guilds and find channels
513
guilds = client.get_guilds()
514
if guilds['data']['guilds']:
515
guild_id = guilds['data']['guilds'][0]['id']
516
channels = client.get_channels(guild_id)
517
518
# Find voice channel
519
voice_channels = [c for c in channels['data']['channels'] if c['type'] == 2]
520
if voice_channels:
521
voice_channel_id = voice_channels[0]['id']
522
523
# Select voice channel
524
client.select_voice_channel(voice_channel_id)
525
print(f"Selected voice channel: {voice_channels[0]['name']}")
526
527
client.close()
528
```