You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Ren'Py Cue lets you add your own sound effects, music, and video effects to [Ren'Py](https://www.renpy.org/) visual novels while you play — without editing the game's scripts.
7
+
Ren'Py Cue lets you add your own sound effects, music, and video effects to [Ren'Py](https://www.renpy.org/) visual novels while you play, without editing the game's scripts.
8
+
4
9
5
-
Open Cue over the game, add sounds to the current image, dialogue, video, or other trigger, and Cue remembers your setup and plays them automatically when that trigger happens again.
10
+
**Need help, want to share your setup, or just hang out? [Join the Cue Discord](https://discord.gg/kAVtFGcQYm)**
6
11
7
-
<sub>Cue was built with AVNs in mind, and the official SFX pack contains NSFW audio. Cue itself works the same on any Ren'Py game, and you can load your own SFX instead if you'd rather keep things SFW.</sub>
12
+
## Contents
13
+
14
+
*[Getting Started](#getting-started)
15
+
*[How Cue Works](#how-cue-works)
16
+
*[What You Can Do](#what-you-can-do)
17
+
*[Video Speed & Effects](#video-speed--effects)
18
+
*[Intensity Groups](#intensity-groups)
19
+
*[Using Cue With Multiple Games](#using-cue-with-multiple-games)
20
+
*[Settings and Your Data](#settings-and-your-data)
21
+
*[Requirements](#requirements)
22
+
*[For Developers](#for-developers)
8
23
9
24
## Getting Started
10
25
11
26
### 1. Install Cue
12
27
13
-
1. Download and extract Cue.
14
-
2. Open the game's `game` folder.
15
-
3. Copy the `renpy_cue` folder into it.
28
+
1. Download and extract the [latest release](https://github.com/guanzo/renpy-cue/releases/latest).
29
+
2. Drop the `renpy_cue` folder into the game's `game` folder.
16
30
17
31
```text
18
32
Your Game/
19
-
└── game/
20
-
└── renpy_cue/
21
-
└── cue_lib/
33
+
└─ game/
34
+
└─ renpy_cue/
22
35
```
23
36
24
37
### 2. Add some sounds
25
38
26
-
Cue needs sound files before it can play anything. Download the Cue SFX pack and extract it. Then open Cue, go to **SFX Library**, and click **Open SFX Folder**. Copy the extracted audio files into the folder that opens.
39
+
Cue needs sound files before it can play anything. You can start with either of these:
27
40
28
-
### 3. Add your first sound effect
41
+
-**[Cue NSFW SFX Pack](https://github.com/guanzo/renpy-cue/releases/latest/download/cue_sfx.zip)**: A curated collection selected for Cue.
42
+
-**[OPENNSFW](https://opennsfw.carrd.co/)**: High quality SFX + Voice Pack. Contains Free and Paid versions.
29
43
30
-
1. Play until you reach an image where you want a sound.
31
-
2. Press `` ` `` (backtick) or `Shift+Alt+E` to open Cue.
32
-
3. Find a sound in **SFX Library**.
33
-
4. Click the **+** button.
34
-
5. If the current image doesn't have a pool yet, Cue creates one automatically.
44
+
Download and extract the pack you want to use. Then run the game, open Cue, go to **SFX Library**, and click **Open SFX Folder**. Copy the extracted audio files into the folder that opens.
35
45
36
-
**[Screenshot: the game with the Cue overlay open, sitting on an image.]** Annotate ① the Image SFX pool / active pool, and ② the SFX Library panel.
46
+
Cue was built with AVNs in mind, but Cue itself works the same on any Ren'Py game.
37
47
38
-
### 4. Keep playing
48
+
### 3. Add your first sound effect
39
49
40
-
Close Cue and continue playing. When the same image appears again, Cue plays sounds from its pool automatically.
50
+
1. Start a replay and play until you reach an image where you want a sound.
51
+
2. Press `` ` `` (backtick) or `Shift+Alt+E` to open Cue.
52
+
3. Find a sound in **SFX Library** and click the **+** button.
53
+
4. The next time this image appears on screen, your chosen sound will play.
41
54
42
55
## How Cue Works
43
56
44
57
Cue attaches **SFX pools** to triggers in a game.
45
58
46
59
A pool is a collection of sound files and folders. When its trigger occurs, Cue plays from that pool. A trigger can be:
47
60
48
-
- an image
49
-
- a dialogue line
50
-
- a video timestamp
51
-
- a repeating loop
52
-
- a screen shake
61
+
* an image
62
+
* a dialogue line
63
+
* a video timestamp
64
+
* a repeating loop
65
+
* a screen shake
66
+
67
+
A trigger can have more than one pool.
53
68
54
-
A trigger can have more than one pool. The **active pool** is the one you're currently editing and the one new sounds are added to.
69
+
Pools can overlap when they play. More than one sound can play at once, and each pool can be set to overlap freely, cross-fade, or wait for a quiet moment before playing. This is an advanced setting you can leave alone until you need it.
55
70
56
-
Pools can also overlap when they play — more than one sound can sound at once, and each pool can be set to overlap freely, cross-fade, or wait for a quiet moment before playing. This is an advanced setting you can leave alone until you need it.
71
+
<b>You can add individual files to a pool, but folders are recommended.</b> Any changes you make to a folder's contents are automatically reflected in the pool, so you can add or remove files later without updating the pool itself.
72
+
73
+
Some games simulate video using sequences of images rather than actual video files. These sequences cannot currently be used as triggers, but support is planned for a future version.
57
74
58
75
## What You Can Do
59
76
60
-
-**Add sound effects** to images, dialogue, videos, loops, and screen shakes.
61
-
-**Build reusable SFX pools** from your own files and folders, and save common setups as **presets**.
62
-
-**Customize replay music** with your own music or the game's existing tracks.
63
-
-**Add sounds to videos**with draggable timeline markers.
64
-
-**Create video speed variants**and switch or sequence between speeds while playing.
65
-
-**Reuse your setup across games**with shared audio, music, presets, and configuration.
77
+
***Add sound effects** to triggers.
78
+
***Build reusable SFX pools** from your own files and folders, and save common setups as **presets**.
79
+
***Customize replay music** with your own music or the game's existing tracks.
80
+
***Create video speed variants**and switch or sequence between speeds while playing.
81
+
***Reuse your setup across games**with shared audio, music, presets, and configuration.
82
+
***Export and import**your Cue setup to share it with others or move it to different machines.
66
83
67
84
## Video Speed & Effects
68
85
69
86
**Requires ffmpeg.**
70
87
71
-
Cue can pre-render slow-motion or fast-motion copies of any movie, then let you switch speeds while playing — including multi-speed sequences and procedural **auto-speed** rhythms (roller_coaster, build_up, edge, tease, and more) that vary each playthrough.
88
+
Cue can create slow-motion or fast-motion copies of any movie, then let you switch speeds while playing. You can also create multi-speed sequences and use procedural **auto-speed** rhythms such as `roller_coaster`, `build_up`, `edge`, and `tease` that vary each playthrough.
89
+
90
+
You only need to place Video SFX markers once, on the original video. When you switch to a speed variant, Cue automatically scales every marker's timestamp to match, so there's no need to re-time or re-place anything for each speed.
91
+
92
+
## Intensity Groups
93
+
94
+
Intensity Groups tie your sound effects to video speed. As a video speeds up or slows down, Cue automatically swaps in sounds that match, so slower speeds can use softer, sparser sounds while faster speeds use louder and more frequent ones.
95
+
96
+
It's the feature that brings everything together: video SFX, loop SFX, loop SFX frequency, and volume can all react alongside video speed instead of feeling like separate effects layered on top of each other.
72
97
73
98
## Using Cue With Multiple Games
74
99
@@ -83,31 +108,26 @@ If you have Cue installed in several games and want one copy of the code to serv
83
108
<game2>/game/renpy_cue/cue_lib -> <your shared copy of cue_lib>
84
109
```
85
110
86
-
An update to the shared copy then propagates to every game at once. On Windows, use a directory junction (`mklink /J …`). Your **data** — markers, presets, audio, music — is already shared machine-wide through the data directory below, so only the code needs the symlink.
87
-
88
-
## Settings and Your Data
89
-
90
-
Press `` ` `` (backtick) or `Shift+Alt+E` to open the Cue overlay. **Settings** is where you can:
111
+
An update to the shared copy then propagates to every game at once. On Windows, use a directory junction (`mklink /J …`).
91
112
92
-
- relocate the **Cue Data Directory**;
93
-
- view, rebind, or reset every hotkey.
113
+
Your **data** (markers, presets, audio, music, and other configuration) is already shared machine-wide through Cue's data directory, so only the code needs to be shared.
94
114
95
-
Cue keeps your SFX and music, pools and markers, presets, and generated video variants in one shared data folder, used by every game where Cue is installed.
115
+
## Cue Data Folder
96
116
97
-
Cue also keeps **automatic hourly and manual backups** as zip files, and supports **undo/redo** (up to 20 steps) and **copy/paste** of a pool's configuration, so you can experiment without losing your setup.
117
+
Cue keeps your SFX and music, pools and markers, presets, and generated video variants in one shared data folder used by every game where Cue is installed.
***Linux:**`$XDG_DATA_HOME/renpy_cue`, or `~/.local/share/renpy_cue`
104
124
105
-
You can also override the location with the `RENPY_CUE_DIR` environment variable.
125
+
You can change the data folder location in Cue's settings, or override it with the `RENPY_CUE_DIR` environment variable.
106
126
107
127
## Requirements
108
128
109
-
-**Ren'Py 7.4 or newer** — works on both the 7.x (Python 2) and 8.x (Python 3) engine generations.
110
-
-**ffmpeg 5 or newer**— only required for creating video speed variants. Must be on `PATH`, or pointed to with the `RENPY_CUE_FFMPEG`/`RENPY_CUE_FFPROBE` environment variables.
129
+
***Ren'Py 7.4 or newer:** works on both the 7.x (Python 2) and 8.x (Python 3) engine generations.
130
+
***ffmpeg 5 or newer:** only required for creating video speed variants. It must be on `PATH`, or pointed to with the `RENPY_CUE_FFMPEG`and`RENPY_CUE_FFPROBE` environment variables.
111
131
112
132
## For Developers
113
133
@@ -121,15 +141,15 @@ You can also override the location with the `RENPY_CUE_DIR` environment variable
121
141
122
142
### Compatibility
123
143
124
-
Code must work on **Ren'Py 7.4.x and up**, which means both the 7.x (Python 2) and 8.x (Python 3) engine generations. The 7.x constraint forbids f-strings, type hints, and other Python 3-only syntax in `.py` files. The full rules are in `CLAUDE.md`.
144
+
Code must work on **Ren'Py 7.4.x and up** — both the 7.x (Python 2) and 8.x (Python 3) engine generations. The 7.x constraint forbids f-strings, type hints, and other Python 3-only syntax in `.py` files. Full rules are in `CLAUDE.md`.
125
145
126
146
### Tooling
127
147
128
148
-`bin/lint.sh` — runs pyright on `cue_lib/` plus a 120-character line-length check. Prints `CLEAN` or exits nonzero.
129
-
-`bin/test.sh` — `poetry run pytest tests/ -q` (headless unit tests against the mock runtime).
130
-
-`bin/test_harness.sh <sdk>/renpy.sh` — runs the in-engine testcases harness against a real Ren'Py SDK (screen/engine code that pytest's mock can't drive). Picks `testcases_modern.rpy` (8.x) or `testcases_legacy.rpy` (7.x) based on the SDK version.
149
+
-`bin/test.sh` — `poetry run pytest tests/ -q`, the headless unit suite against the mock runtime.
150
+
-`bin/test_harness.sh <sdk>/renpy.sh` — runs the in-engine testcase harness against a real Ren'Py SDK, for screen/engine code the pytest mock can't drive. Picks `testcases_modern.rpy` (8.x) or `testcases_legacy.rpy` (7.x) based on the SDK version.
131
151
132
-
CI runs the harness against pinned Ren'Py **7.4.10** and **8.5.3** SDKs, plus lint and pytest on every push/PR.
152
+
CI runs the harness against pinned Ren'Py **7.4.10** and **8.5.3** SDKs, plus lint and pytest, on every push and pull request.
0 commit comments