0
# Rich Presence Management
1
2
Simplified interface for updating Discord Rich Presence with activity information, timestamps, images, and party details. The Presence and AioPresence classes provide focused functionality for applications that only need to display rich status information without requiring full Discord RPC capabilities.
3
4
## Capabilities
5
6
### Synchronous Presence Client
7
8
The Presence class provides a synchronous interface for Rich Presence management with automatic event loop handling.
9
10
```python { .api }
11
class Presence(BaseClient):
12
def __init__(self, client_id: str, **kwargs):
13
"""
14
Initialize synchronous presence client.
15
16
Parameters:
17
- client_id (str): Discord application client ID
18
- loop: Optional event loop (auto-created if not provided)
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 connect(self):
28
"""
29
Connect to Discord RPC.
30
31
Raises:
32
- DiscordNotFound: Discord not installed or running
33
- InvalidPipe: Pipe not found
34
- ConnectionTimeout: Unable to connect in time
35
- InvalidID: Client ID is invalid
36
"""
37
```
38
39
```python { .api }
40
def update(self, pid: int = None, state: str = None, details: str = None,
41
start: int = None, end: int = None,
42
large_image: str = None, large_text: str = None,
43
small_image: str = None, small_text: str = None,
44
party_id: str = None, party_size: list = None,
45
join: str = None, spectate: str = None,
46
match: str = None, buttons: list = None,
47
instance: bool = True, payload_override: dict = None):
48
"""
49
Update Rich Presence activity.
50
51
Parameters:
52
- pid (int): Process ID (default: current process)
53
- state (str): Current player status (e.g., "In Main Menu")
54
- details (str): What the player is currently doing (e.g., "Playing Solo")
55
- start (int): Unix timestamp when activity started
56
- end (int): Unix timestamp when activity will end
57
- large_image (str): Key for large image asset
58
- large_text (str): Tooltip text for large image
59
- small_image (str): Key for small image asset
60
- small_text (str): Tooltip text for small image
61
- party_id (str): Unique party identifier
62
- party_size (list): [current_size, max_size] party size
63
- join (str): Secret for joining the game
64
- spectate (str): Secret for spectating the game
65
- match (str): Secret for match-based games
66
- buttons (list): List of button dictionaries with 'label' and 'url'
67
- instance (bool): Whether this is a game instance
68
- payload_override (dict): Complete payload override
69
70
Returns:
71
dict: Discord RPC response
72
73
Raises:
74
- PipeClosed: Connection was closed
75
- ResponseTimeout: No response received in time
76
- ServerError: Discord server error
77
"""
78
```
79
80
```python { .api }
81
def clear(self, pid: int = None):
82
"""
83
Clear current Rich Presence activity.
84
85
Parameters:
86
- pid (int): Process ID (default: current process)
87
88
Returns:
89
dict: Discord RPC response
90
"""
91
```
92
93
```python { .api }
94
def close(self):
95
"""Close the connection to Discord."""
96
```
97
98
### Asynchronous Presence Client
99
100
The AioPresence class provides an asynchronous interface for Rich Presence management, suitable for async applications.
101
102
```python { .api }
103
class AioPresence(BaseClient):
104
def __init__(self, client_id: str, **kwargs):
105
"""
106
Initialize asynchronous presence client.
107
108
Parameters:
109
- client_id (str): Discord application client ID
110
- loop: Optional event loop (auto-created if not provided)
111
- handler: Optional async error handler function
112
- pipe (int): Optional specific pipe number (0-9)
113
- connection_timeout (int): Connection timeout in seconds (default: 30)
114
- response_timeout (int): Response timeout in seconds (default: 10)
115
"""
116
```
117
118
```python { .api }
119
async def connect(self):
120
"""
121
Connect to Discord RPC asynchronously.
122
123
Raises:
124
- DiscordNotFound: Discord not installed or running
125
- InvalidPipe: Pipe not found
126
- ConnectionTimeout: Unable to connect in time
127
- InvalidID: Client ID is invalid
128
"""
129
```
130
131
```python { .api }
132
async def update(self, pid: int = None, state: str = None, details: str = None,
133
start: int = None, end: int = None,
134
large_image: str = None, large_text: str = None,
135
small_image: str = None, small_text: str = None,
136
party_id: str = None, party_size: list = None,
137
join: str = None, spectate: str = None,
138
match: str = None, buttons: list = None,
139
instance: bool = True):
140
"""
141
Update Rich Presence activity asynchronously.
142
143
Parameters:
144
- pid (int): Process ID (default: current process)
145
- state (str): Current player status
146
- details (str): What the player is currently doing
147
- start (int): Unix timestamp when activity started
148
- end (int): Unix timestamp when activity will end
149
- large_image (str): Key for large image asset
150
- large_text (str): Tooltip text for large image
151
- small_image (str): Key for small image asset
152
- small_text (str): Tooltip text for small image
153
- party_id (str): Unique party identifier
154
- party_size (list): [current_size, max_size] party size
155
- join (str): Secret for joining the game
156
- spectate (str): Secret for spectating the game
157
- match (str): Secret for match-based games
158
- buttons (list): List of button dictionaries
159
- instance (bool): Whether this is a game instance
160
161
Returns:
162
dict: Discord RPC response
163
"""
164
```
165
166
```python { .api }
167
async def clear(self, pid: int = None):
168
"""
169
Clear current Rich Presence activity asynchronously.
170
171
Parameters:
172
- pid (int): Process ID (default: current process)
173
174
Returns:
175
dict: Discord RPC response
176
"""
177
```
178
179
```python { .api }
180
def close(self):
181
"""Close the connection to Discord."""
182
```
183
184
## Usage Examples
185
186
### Basic Rich Presence
187
188
```python
189
from pypresence import Presence
190
import time
191
192
# Initialize and connect
193
RPC = Presence("your_client_id_here")
194
RPC.connect()
195
196
# Simple status update
197
RPC.update(state="In Main Menu", details="Waiting for match")
198
199
# Rich presence with images and timestamps
200
start_time = int(time.time())
201
RPC.update(
202
state="In Game",
203
details="Level 5 - Dark Forest",
204
start=start_time,
205
large_image="game_logo",
206
large_text="My Amazing Game v1.0",
207
small_image="character_mage",
208
small_text="Playing as Mage"
209
)
210
211
# Party information
212
RPC.update(
213
state="In Lobby",
214
details="Waiting for players",
215
party_id="lobby_12345",
216
party_size=[3, 6]
217
)
218
219
# Interactive buttons
220
RPC.update(
221
state="Streaming",
222
details="Creating awesome content",
223
buttons=[
224
{"label": "Watch Stream", "url": "https://twitch.tv/username"},
225
{"label": "Join Discord", "url": "https://discord.gg/server"}
226
]
227
)
228
229
# Clear presence
230
RPC.clear()
231
RPC.close()
232
```
233
234
### Async Rich Presence
235
236
```python
237
import asyncio
238
from pypresence import AioPresence
239
import time
240
241
async def main():
242
RPC = AioPresence("your_client_id_here")
243
await RPC.connect()
244
245
# Update with activity tracking
246
await RPC.update(
247
state="Playing Solo Campaign",
248
details="Mission 3: Rescue Operation",
249
start=int(time.time()),
250
large_image="mission_3",
251
large_text="Chapter 1: The Beginning",
252
buttons=[{"label": "View Profile", "url": "https://example.com/profile"}]
253
)
254
255
# Keep alive and update periodically
256
for i in range(10):
257
await asyncio.sleep(30)
258
await RPC.update(
259
state=f"Level {i+1}",
260
details="Exploring the world"
261
)
262
263
await RPC.clear()
264
RPC.close()
265
266
asyncio.run(main())
267
```
268
269
### Error Handling
270
271
```python
272
from pypresence import Presence, DiscordNotFound, PipeClosed
273
import time
274
275
try:
276
RPC = Presence("your_client_id")
277
RPC.connect()
278
279
while True:
280
try:
281
RPC.update(state="Online", details="Available for chat")
282
time.sleep(15)
283
except PipeClosed:
284
print("Discord connection lost, reconnecting...")
285
RPC.connect()
286
287
except DiscordNotFound:
288
print("Discord is not running. Please start Discord and try again.")
289
except Exception as e:
290
print(f"An error occurred: {e}")
291
finally:
292
if 'RPC' in locals():
293
RPC.close()
294
```