> 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/configuration/station-configuration.md). # Station Configuration ## Station Configuration Every radio station has its own configuration inside: ``` Config.Stations ``` Each station controls its own music, advertisements, jingles and playback behaviour. Below is an overview of every available setting. *** ## enabled ```lua enabled = true ``` Enables or disables the station broadcast. | Value | Description | | ------- | ---------------------------------------- | | `true` | The station is active and can broadcast. | | `false` | The station is disabled. | > A disabled station will not broadcast, even if it is visible in the radio wheel. *** ## label ```lua label = 'Générations' ``` The name displayed in the radio wheel. This can be changed to anything you'd like. Example: ```lua label = 'Bonsai FM' ``` *** ## icon ```lua icon = 'images/stations/generations.jpg' ``` The station artwork shown inside the radio wheel. The path is relative to the `html` folder. Recommended image size: ``` 512 × 512 pixels ``` If a song doesn't have its own cover artwork, this image will automatically be used as the fallback. *** ## volume ```lua volume = 0.65 ``` Applies a volume multiplier to this station only. Useful if one station is naturally louder or quieter than the others. Examples: | Value | Result | | ------ | ---------------------------- | | `1.0` | Full volume | | `0.8` | 80% volume | | `0.65` | Slightly quieter *(Default)* | | `0.5` | Half volume | *** ## shuffle ```lua shuffle = true ``` Randomises the playlist order every time the resource starts. | Value | Description | | ------- | ----------------------------------- | | `true` | Songs are shuffled. *(Recommended)* | | `false` | Songs play in folder order. | *** ## randomStartTrack ```lua randomStartTrack = true ``` Controls which song the station starts with after a restart. | Value | Description | | ------- | ------------------------------------------- | | `true` | Starts on a random song. | | `false` | Starts with the first song in the playlist. | *** ## randomStartOffset ```lua randomStartOffset = false ``` Controls whether the first song starts from the beginning or from a random position. | Value | Description | | ------- | -------------------------------------------------- | | `true` | Starts part-way through the first song. | | `false` | Starts from the beginning of the song. *(Default)* | This helps make the station feel like it's already broadcasting when enabled. *** ## folder ```lua folder = 'audio/french' ``` Defines where the station's music is stored. Every `.mp3` and `.ogg` file inside this folder will automatically be added after running: ``` scan_media.bat ``` Example: ```lua folder = 'audio/hiphop' ``` *** ## metadata ```lua metadata = { ['song.ogg'] = { title = 'Song Title', artist = 'Artist Name', cover = 'images/covers/song.jpg' } } ``` Allows you to override: * Song title * Artist name * Album artwork Only tracks listed inside this table will use custom metadata. All other songs follow the configured `metadataFallback` behaviour. *** ## Advertisements Every station contains its own advertisement configuration. ```lua ads = { ... } ``` This allows each station to have completely different advertisement behaviour. *** ### ads.enabled ```lua enabled = true ``` Enables advertisements for this station. If disabled, no advertisements or advertisement jingles will play. *** ### ads.minSongs ```lua minSongs = 3 ``` Minimum number of completed songs before an advertisement opportunity. *** ### ads.maxSongs ```lua maxSongs = 6 ``` Maximum number of completed songs before an advertisement opportunity. The script will choose a random number between `minSongs` and `maxSongs`. *** ### ads.chance ```lua chance = 100 ``` Percentage chance that an advertisement will play once the song threshold has been reached. Examples: | Value | Result | | ----- | ---------------------------- | | `100` | Always play an advertisement | | `75` | 75% chance | | `50` | 50% chance | | `25` | 25% chance | *** ### ads.useGlobalAds ```lua useGlobalAds = true ``` Allows this station to use advertisements from: ```lua Config.RadioAds.globalAds ``` Disable this if the station should only play its own advertisements. *** ### ads.useStationAds ```lua useStationAds = true ``` Allows this station to use advertisements defined inside: ```lua stationAds = {} ``` A station can use: * Global advertisements only * Station advertisements only * Both * Neither *** ### stationAds ```lua stationAds = { { file = 'audio/ads/stations/example.ogg', title = 'Commercial Break', artist = 'Advertisement', cover = '' } } ``` Advertisements added here will only play on this station. *** ## Advertisement Jingles Every station supports optional jingles before and after advertisements. *** ### jinglesBefore ```lua jinglesBefore = { { file = 'audio/jingles/example_before.ogg', title = 'Station Identification', artist = 'Radio Jingle', cover = '' } } ``` These jingles play immediately **before** an advertisement. *** ### jinglesAfter ```lua jinglesAfter = { { file = 'audio/jingles/example_after.ogg', title = 'Back to the Music', artist = 'Radio Jingle', cover = '' } } ``` These jingles play immediately **after** an advertisement. This is perfect for station IDs such as: > "You're listening to Bonsai Radio." or > "Back to the music." *** ## Example Station ```lua RADIO_MY_STATION = { enabled = true, label = 'Bonsai FM', icon = 'images/stations/bonsaifm.jpg', volume = 0.65, shuffle = true, randomStartTrack = true, randomStartOffset = false, folder = 'audio/bonsaifm', ads = { enabled = true, minSongs = 3, maxSongs = 5, chance = 100, useGlobalAds = true, useStationAds = true, stationAds = {}, jinglesBefore = {}, jinglesAfter = {} }, metadata = {} } ``` This example includes every available station setting and can be used as a starting point when creating a new station. --- # 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/configuration/station-configuration.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.