> For the complete documentation index, see [llms.txt](https://bonsai-docs.gitbook.io/bonsai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bonsai-docs.gitbook.io/bonsai-docs/bonsai-radio/media-setup/adding-jingles.md). # Adding Jingles ## Adding Jingles Jingles are short station sounds that help give each radio station its own identity. They can be used for: * Station names * Radio transitions * Station slogans * DJ drops * Short sound effects * Music introductions * Branding Jingles are detected automatically by the Bonsai Radio media scanner. *** ### Supported Audio Formats Jingles can use: * `.mp3` * `.ogg` MP3 is the recommended format. *** ### What Is a Jingle? A jingle is normally a short audio clip that identifies the radio station. Example voice lines: ``` You are listening to Bonsai Radio. ``` ``` West Coast Classics — only the greatest hits. ``` ``` This is Générations. ``` Jingles can also contain sound effects, music transitions or short instrumental clips. *** ### Recommended Jingle Length Jingles should normally be short. Recommended length: ``` 2–10 seconds ``` Long jingles may interrupt the flow of the station. {% hint style="info" %} Short jingles generally sound more professional and are less repetitive for regular players. {% endhint %} *** ### Step 1: Find the Jingle Folder Open the media folder belonging to the station. A station folder may look similar to: ``` html/media/generations/ ├── songs/ ├── ads/ └── jingles/ ``` Jingles for this station should be placed inside: ``` html/media/generations/jingles/ ``` For another station: ``` html/media/west_coast/jingles/ ``` {% hint style="warning" %} Jingles are station-specific. Place each jingle inside the folder belonging to the station that should use it. {% endhint %} *** ### Step 2: Add the Jingle Files Copy the jingle audio files into the station's jingle folder. Example: ``` html/media/generations/jingles/generations_station_id.mp3 html/media/generations/jingles/generations_you_are_listening.mp3 html/media/generations/jingles/generations_transition.mp3 ``` Recommended filenames: ``` generations_station_id.mp3 ``` ``` west_coast_classics_intro.mp3 ``` ``` bonsai_radio_transition.mp3 ``` Avoid: * Emojis * Unusual symbols * Extremely long filenames * Complicated punctuation *** ### Step 3: Run the Media Scanner After adding the jingles, run: ``` scan_media.bat ``` The scanner will detect the jingle files and update: ``` data/media_library.json ``` The scanner summary should include the number of jingles found. Example: ``` Songs: 183 Ads: 24 Jingles: 16 ``` {% hint style="warning" %} Do not manually add jingles directly to `media_library.json`.\ The media library is generated automatically and may be replaced whenever the scanner runs. {% endhint %} *** ### Step 4: Restart Bonsai Radio Restart the resource after the scanner has completed: ``` restart bonsai_radio ``` The new jingles should now be available to the station. *** ### Jingle Playback Configuration Jingle playback is controlled inside: ``` config.lua ``` Depending on the installed version, jingle settings may include: * Whether jingles are enabled * How often jingles play * Whether they play before a song * Whether they play after a song * Whether they play after advertisements * Minimum songs between jingles * Maximum songs between jingles Example: ```lua jingles = { enabled = true, playAfterSongs = 3 } ``` With this example, the station may play a jingle after every three songs. *** ### Using Multiple Jingles You can add multiple jingles to the same station. Example: ``` jingles/ ├── station_name.mp3 ├── station_slogan.mp3 ├── dj_drop_01.mp3 ├── dj_drop_02.mp3 └── transition_01.mp3 ``` Using multiple jingles creates more variation and reduces repetition. For a complete station, consider adding: * Two station identification jingles * Two short transition jingles * One station slogan * One advertisement transition *** ### Jingles With Silence Remove unnecessary silence from the beginning and end of jingle files. A jingle containing several seconds of silence can make the station appear to have stopped playing. Recommended: ``` 0–0.2 seconds of silence ``` Not recommended: ``` 2–5 seconds of silence ``` Use an audio editor to trim the file before adding it. *** ### Removing a Jingle To remove a jingle: 1. Delete the file from the station's jingle folder. 2. Run `scan_media.bat`. 3. Restart Bonsai Radio. The scanner will remove the missing file from the generated media library. *** ### Jingle Not Playing Check the following: * Jingles are enabled in `config.lua`. * The file is MP3 or OGG. * The file is inside the correct station's jingle folder. * The scanner was run after adding the file. * The scanner detected at least one jingle. * The media library was generated successfully. * The station has jingle playback enabled. * Enough songs have played to trigger a jingle. * Bonsai Radio was restarted. *** ### Jingles Playing Too Often Increase the configured number of songs between jingles. Example: ```lua playAfterSongs = 5 ``` This will play fewer jingles than: ```lua playAfterSongs = 1 ``` Recommended starting point: ``` One jingle every 3–5 songs ``` Shorter jingles can usually play more frequently than long jingles. *** ### Jingle and Advertisement Transitions Jingles can be used to make advertisements feel like part of the station. A typical sequence could be: ``` Song ↓ Advertisement jingle ↓ Advertisement ↓ Station jingle ↓ Next song ``` Example advertisement transition: ``` Bonsai Radio will return after these messages. ``` Example return transition: ``` You are back with Bonsai Radio. ``` This can make the station sound more realistic and professionally produced. *** ### Recommended Workflow ``` Place MP3 or OGG files in appropiate folders ↓ Run auto_scan_media.bat ↓ Restart Bonsai Radio ↓ Test it in-game ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bonsai-docs.gitbook.io/bonsai-docs/bonsai-radio/media-setup/adding-jingles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.