> 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-advertisements.md). # Adding Advertisements ## Adding Advertisements Bonsai Radio supports advertisements that can automatically play between songs. Advertisements can be configured in two different ways: * **Station-specific advertisements** only play on one radio station. * **Global advertisements** can play across all stations that allow global advertisements. Advertisements are added as audio files and detected by the Bonsai Radio media scanner. *** ### Supported Audio Formats Advertisements can use: * `.mp3` * `.ogg` MP3 is recommended for most servers. {% hint style="warning" %} Avoid using very large or uncompressed audio files. All included media increases the resource download size for players. {% endhint %} *** ### Station-Specific and Global Advertisements Bonsai Radio supports two types of advertisements. #### Station-Specific Advertisements Station-specific advertisements belong to one radio station. For example, an advertisement placed in the advertisement folder for Générations will only be available to Générations. This is useful for advertisements that should match the style, language or audience of a particular station. Examples include: * A French advertisement for a French radio station * A country-themed advertisement * A hip-hop event promotion * A station-specific sponsor message #### Global Advertisements Global advertisements are shared between radio stations. They can be used by every station that has global advertisements enabled. This is useful for server-wide announcements and businesses that should be advertised across the entire radio network. Examples include: * Vehicle dealership advertisements * Restaurant advertisements * Mechanic shop advertisements * Server events * Government announcements * Bonsai product advertisements {% hint style="info" %} A station can use its own advertisements, global advertisements or a combination of both, depending on its configuration. {% endhint %} *** ### Adding a Station-Specific Advertisement #### Step 1: Find the Station Advertisement Folder Open the media folder belonging to the radio station. The structure may look similar to: ``` html/media/generations/ ├── songs/ ├── ads/ └── jingles/ ``` Advertisements for this station should be placed inside: ``` html/media/generations/ads/ ``` Another station may use: ``` html/media/west_coast/ads/ ``` The exact folder name depends on the media folder configured for the station. *** #### Step 2: Add the Advertisement Files Copy the advertisement files into the station's advertisement folder. Example: ``` html/media/generations/ads/french_nightclub_event.mp3 html/media/generations/ads/parisian_restaurant.mp3 ``` These advertisements will only be available to the Générations station. *** ### Adding a Global Advertisement #### Step 1: Find the Global Advertisement Folder Open the shared global advertisement folder included with Bonsai Radio. The exact folder path can be found in the media configuration included with your version of the resource. It may look similar to: ``` html/media/global/ads/ ``` or: ``` html/media/ads/ ``` {% hint style="warning" %} Use the exact global advertisement folder included with your version of Bonsai Radio. Do not create a new folder path unless the configuration has been updated to use it. {% endhint %} *** #### Step 2: Add the Global Advertisement Files Copy the advertisement audio files into the global advertisement folder. Example: ``` html/media/global/ads/bonsai_ad.mp3 html/media/global/ads/server_dealership.mp3 html/media/global/ads/mechanic_shop.mp3 html/media/global/ads/weekend_event.mp3 ``` These advertisements can be used across multiple radio stations. *** ### Recommended Filenames Use simple and clear filenames. Recommended: ``` bonsai_ad.mp3 server_car_dealership.mp3 mechanic_shop_ad.ogg weekend_event.ogg ``` Avoid filenames containing: * Emojis * Unusual symbols * Extremely long names * Complicated punctuation * Multiple consecutive spaces *** ### Run the Media Scanner After adding either station-specific or global advertisements, run: ``` scan_media.bat ``` The scanner detects the advertisement files and updates: ``` data/media_library.json ``` The scanner summary should display the number of advertisements found. Example: ``` Songs: 183 Ads: 24 Jingles: 16 ``` {% hint style="warning" %} Do not manually add advertisements to `data/media_library.json`.\ This file is generated automatically and can be replaced the next time the media scanner runs. {% endhint %} *** ### Restart Bonsai Radio After the scanner finishes, restart the resource: ``` restart bonsai_radio ``` You can also restart the entire server. The newly added advertisements should now be available. *** ### Advertisement Configuration Advertisement behaviour is controlled in: ``` config.lua ``` Depending on the installed version, advertisement settings may control: * Whether advertisements are enabled * Whether a station uses global advertisements * Whether a station uses its own advertisements * How many songs play between advertisements * Whether global and station-specific advertisements are mixed * How advertisements are selected * Whether the same advertisement can repeat Use the exact settings included in your version of Bonsai Radio. *** ### Using Global and Station Advertisements Together A radio station can use both advertisement types. For example: ``` Générations advertisement pool ├── Global advertisements │ ├── bonsai_ad.mp3 │ ├── server_dealership.mp3 │ └── mechanic_shop.mp3 │ └── Station-specific advertisements ├── french_nightclub_event.mp3 └── parisian_restaurant.mp3 ``` This allows server-wide advertisements to play while still giving each station its own unique content. *** ### When to Use Global Advertisements Global advertisements work best for content that is relevant to most players. Examples: * Server announcements * Public events * Major businesses * Dealership promotions * Mechanic services * Restaurant promotions * New server features * Bonsai products *** ### When to Use Station-Specific Advertisements Station-specific advertisements work best when the content should match a particular station. Examples: * Language-specific advertisements * Genre-specific events * Station sponsors * Localized businesses * Themed advertisements * Station branding *** ### Recommended Advertisement Length Advertisements should normally be: ``` 10–30 seconds ``` Long advertisements can become disruptive, especially when they play frequently. A recommended starting balance is: ``` 1 advertisement every 3–5 songs ``` The ideal frequency depends on the average song length and the number of advertisements available. *** ### Using Multiple Advertisements Add several advertisements to reduce repetition. Example global pool: ``` global/ads/ ├── bonsai_ad.mp3 ├── mechanic_shop.mp3 ├── dealership_sale.mp3 ├── restaurant_ad.mp3 └── weekend_event.mp3 ``` Example station pool: ``` generations/ads/ ├── french_club_night.mp3 ├── paris_restaurant.mp3 └── generations_sponsor.mp3 ``` A larger advertisement pool provides more variety for players. *** ### Removing an Advertisement To remove an advertisement: 1. Delete the audio file from its advertisement folder. 2. Run `scan_media.bat`. 3. Restart Bonsai Radio. This applies to both global and station-specific advertisements. The scanner will remove the missing file from the generated media library. *** ### Moving an Advertisement An advertisement can be moved between global and station-specific folders. For example, to turn a station-specific advertisement into a global advertisement: 1. Remove it from the station advertisement folder. 2. Place it in the global advertisement folder. 3. Run `scan_media.bat`. 4. Restart Bonsai Radio. *** ### Advertisement Not Playing Check the following: * Advertisements are enabled in `config.lua`. * The audio file is MP3 or OGG. * The file is inside a valid advertisement folder. * The media scanner was run after adding the file. * The scanner detected the advertisement. * `data/media_library.json` was generated successfully. * Bonsai Radio was restarted. * Enough songs have played to trigger an advertisement. * The station allows the type of advertisement you added. For a global advertisement, also verify that: * The advertisement is inside the global advertisement folder. * The station is configured to use global advertisements. For a station-specific advertisement, verify that: * The advertisement is inside the correct station folder. * The station is configured to use its own advertisements. *** ### Advertisement Plays on the Wrong Station First determine whether the advertisement is global or station-specific. A global advertisement may play across several stations. To limit it to one station: 1. Remove it from the global advertisement folder. 2. Place it in the required station's advertisement folder. 3. Run `scan_media.bat`. 4. Restart Bonsai Radio. *** ### Advertisement Plays Too Often Increase the configured number of songs between advertisement breaks. A higher value results in fewer advertisements. For example: ``` 2 songs between advertisements = frequent advertisements ``` ``` 6 songs between advertisements = less frequent advertisements ``` A recommended starting point is: ``` 4 songs between advertisements ``` Adjust this based on the length of your songs and advertisements. *** ### Recommended Workflow ``` Place MP3 or OGG files in the correct advertisement folder ↓ Run auto_scan_media.bat ↓ Check the scanner summary ↓ Restart Bonsai Radio ↓ Test several stations in-game ``` *** ### Quick Checklist Before testing, verify that: * The file is MP3 or OGG. * The advertisement is in the correct folder. * You chose global or station-specific placement. * The station allows that advertisement type. * `scan_media.bat` completed successfully. * `data/media_library.json` was updated. * Bonsai Radio was restarted. --- # 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-advertisements.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.