New and extended guides for several open issues

docs/development/bounties.md

@@ -1,5 +1,8 @@
 # Libretro open source bounties
 
+!!! Warning "Bountysource no longer operates"
+    Bountysource, the service this page describes, has stopped working: bounties can no longer be funded, claimed or paid out through it. Libretro has not chosen a replacement yet. The rest of this page is kept to explain how the bounties used to work.
+
 !!! Info "What is an Open Source Bounty?"
     Bounties are usually offered as an incentive for fixing software bugs or implementing minor features. Bounty driven development is one of the Business models for open-source software. The compensation offered for an open-source bounty is usually small. Source: [Wikipedia](https://en.wikipedia.org/wiki/Open-source_bounty)
 

docs/guides/cli-intro.md

@@ -41,3 +41,29 @@ Use the `--help` help flag to display RetroArch's built-in CLI documentation. Yo
 
 ### retroarch --features
 If you're unsure if a particular feature is compiled in, execute `retroarch --features`
+
+## On Android
+
+Android has no `retroarch` executable to run. RetroArch is started as an activity instead, with `am start` from `adb shell` or from another app or launcher, and takes its arguments as intent extras:
+
+```
+am start -n com.retroarch/com.retroarch.browser.retroactivity.RetroActivityFuture \
+  -e ROM "/storage/emulated/0/ROMs/snes/game.sfc" \
+  -e LIBRETRO "/data/data/com.retroarch/cores/snes9x_libretro_android.so"
+```
+
+The package is `com.retroarch`, `com.retroarch.aarch64` or `com.retroarch.ra32`, depending on which RetroArch is installed; the activity name is the same in all three. The core's full path is the core directory shown in `Settings > Directory > Cores` followed by the core's file name.
+
+| Extra | Meaning |
+|---|---|
+| `ROM` | Content to load, as a full path. |
+| `LIBRETRO` | Core to load it with, as a full path. |
+| `CONFIGFILE` | Configuration file to use instead of the default `retroarch.cfg`. |
+| `QUITFOCUS` | If present (with any value), RetroArch quits instead of staying in the background when it loses focus, for example when you switch back to the launcher. |
+| `REFRESH` | Display refresh rate to ask for, in Hz, unless a display mode is chosen in the settings. |
+| `IME` | Input method (on-screen keyboard) to use. |
+| `DATADIR`, `APK`, `SDCARD`, `EXTERNAL` | The app's data, APK and storage directories. |
+
+Only `ROM` and `LIBRETRO` are needed to start a game. RetroArch works everything else out itself when it is not given: the configuration file, the directories and the input method.
+
+If RetroArch is already running with other content, starting it with a different `ROM` or `LIBRETRO` closes that and starts afresh with the new one.

docs/guides/disc-images.md

@@ -0,0 +1,41 @@
+# Disc Images: CUE, CHD and M3U
+
+Games that came on CD, GD-ROM or DVD are loaded from disc images. This page explains the common formats, how to shrink them into CHD files, and how to keep multi-disc games together.
+
+## CUE/BIN and other formats
+
+- **CUE/BIN** is the most common CD format. The `.bin` files hold the data and audio tracks, and the small `.cue` file lists them. **Always load the `.cue` file**, not a `.bin`: without the cue sheet the core does not know where the tracks are, and CD audio or whole games fail. The cue sheet names the `.bin` files it uses, so keep them in the same folder and do not rename them without editing the `.cue` to match.
+- **ISO** holds a single data track. It is fine for DVD games and data-only CDs, but it cannot hold CD audio tracks.
+- **GDI** is the Dreamcast GD-ROM equivalent of a cue sheet, loaded the same way.
+- **CHD** stores any of the above, tracks included, as one compressed file. See below.
+
+Which formats a core accepts is listed under **Extensions** on its page in the [core library](core-list.md).
+
+## CHD
+
+CHD ("Compressed Hunks of Data") comes from MAME. A CHD is lossless: it holds the same tracks as the original image, usually in noticeably less space, and a multi-file CUE/BIN game becomes a single file.
+
+Cores that read CHD include those for PlayStation (Beetle PSX, SwanStation, PCSX ReARMed, DuckStation), PlayStation 2, PSP (PPSSPP), Saturn, Dreamcast (Flycast), Sega CD (Genesis Plus GX, PicoDrive), PC Engine CD and PC-FX, Neo Geo CD, 3DO (Opera), CD-i and several others; check the core's page to be sure.
+
+### Making CHD files with chdman
+
+CHD files are made with `chdman`, which ships with MAME: it is in the MAME download for Windows, and in the `mame-tools` package on most Linux distributions.
+
+| Source | Command |
+|---|---|
+| CD image (`.cue`, `.gdi`, or a CD `.iso`) | `chdman createcd -i "Game.cue" -o "Game.chd"` |
+| DVD image (`.iso`), for example PlayStation 2 DVD games | `chdman createdvd -i "Game.iso" -o "Game.chd"` |
+
+Make one CHD per disc. To get the original image back, use `chdman extractcd -i "Game.chd" -o "Game.cue" -ob "Game.bin"` (or `extractdvd` for DVDs).
+
+Some cores need a CHD made a particular way, for example PSP games made with `createdvd` and a smaller hunk size. When a core's page says so, follow it.
+
+## Multi-disc games and M3U
+
+A game on several discs is loaded through an `.m3u` file: a text file listing its discs, one per line. Loading the `.m3u` makes all the discs available to RetroArch's disc control, keeps one set of saves for the whole game, and lets you switch discs from the Quick Menu. [Disc Swapping](disc-swapping.md) explains how to write the file and switch discs.
+
+List the files you would load for each disc: the `.cue` files for CUE/BIN, or the `.chd` files.
+
+## Multi-disc games in playlists
+
+When a content scan (`Import Content > Content Scan`, called Manual Scan in older versions) finds `.m3u` files, RetroArch adds one entry for each `.m3u`, named after the game without its disc number, and leaves out the separate disc files the `.m3u` lists. Keep each game's `.m3u` in the scanned folder together with its discs, or anywhere the scan reaches, and the playlist shows one entry per game instead of one per disc.

docs/guides/disc-swapping.md

@@ -25,7 +25,7 @@ If you don't or can't use a playlist, you can append a disk image to the list on
 
 Multi-CD images are typically handled with an .m3u playlist file. In this case, you can swap disks by cycling through the `Disc Index` setting.
 
-You can start a game by loading its M3U file, through `Load Content` or Playlists (This will have to be added manually to your Playlists, as scanning for content will not do so).
+You can start a game by loading its M3U file, through `Load Content` or Playlists. A content scan adds the M3U file to the playlist as one entry for the game, instead of one entry per disc (see [Disc Images](disc-images.md#multi-disc-games-in-playlists)).
 
 ### Making an M3U playlist file
 You can make an M3U playlist file using a simple text editor.

docs/guides/optimal-vsync.md

@@ -104,6 +104,19 @@ Notable internal RetroArch statistics regarding frame pacing are:
       - Under `System->Video Settings->Synchronization`, `Hard GPU Sync`, `Max Swapchain Images`, or `Waitable Swapchains`, any of which might be available with your current renderer API, are designed to reduce latency by limiting how many frames ahead that the cpu can calculate beyond the currently displayed frame. If you are still experiencing frame pacing issues having reached this point in the document, and care more about that than increased latency, you can disable `Hard GPU Sync`, `Waitable Swapchains`, or increase the value of `Max Swapchain Images` to give your system more performance headroom.
 
 
+## Maximum Timing Skew: speed and pitch against smoothness
+
+Most content does not run at exactly your display's refresh rate. `Maximum Timing Skew` (`Settings > Audio > Synchronization`, 0.05 by default) decides what RetroArch does about the difference when `Sync to Exact Content Rate` is not in use:
+
+- **Within the skew.** When the content's rate differs from the display's rate (divided by the swap interval, black frame insertion and shader subframes) by no more than the skew, as a fraction, RetroArch runs the content at the display's rate. Every frame is shown once and scrolling is smooth. The audio is resampled to match, so the game runs faster or slower than on real hardware by that difference, and the music plays higher or lower by the same amount.
+- **Beyond the skew.** RetroArch leaves the content at its own rate and logs "Timings deviate too much. Will not adjust." The game keeps its original speed and pitch, and the display repeats or skips frames to make up the difference, which shows as judder.
+
+For example, an arcade game made for 57.5 Hz is 4.2% away from a 60 Hz display (1 - 57.5 / 60 = 0.042). With the default skew of 0.05 it runs at 60 Hz: smooth, but 4.3% fast and 4.3% high in pitch. With the skew set below 0.042, for instance 0.03, it runs at its correct speed and pitch but with occasional judder. 50 Hz PAL content is 17% away from 60 Hz and is only sped up if the skew is raised to at least 0.17.
+
+Which of the two is better is a matter of taste: RetroArch's default favours smooth motion for content close to the display's rate. A display that runs at the content's own rate, or a VRR display with `Sync to Exact Content Rate`, avoids the compromise altogether.
+
+The small, continuous corrections that keep audio and video in step once the rates are matched are the job of dynamic rate control, set by `Audio Rate Control Delta` in the same menu; see [Dynamic Rate Control](../development/cores/dynamic-rate-control.md).
+
 ## Further Considerations
 
 If you've gone through all the above, there is not much more to configure settings-wise. It is possible your hardware is just not capable of running the desired content at full speed. You can try to see if an alternative core exists for your content that is perhaps designed to run on lower specification hardware than the one you were previously using. Also (though no specific offenders will be named as this can change for better or worse with any core update any given day) some content on some cores simply have somewhat poorer timing control. Odds are higher of finding this on 5th generation and beyond console cores that are dealing with content that ran at very unstable framerates on original hardware. 

docs/guides/roms-playlists-thumbnails.md

@@ -108,6 +108,42 @@ The ROM's corresponding `db_name` is `MAME 2003-Plus.lpl` which tells the menu d
 !!! Alert
     You can omit the CRC or Serial for a manually created playlist entry by using the word `DETECT`  instead, although it may limit your ability to use netplay for this playlist entry.
 
+#### Playlist fields
+
+Besides `version` and `items`, a playlist written by RetroArch can carry these top-level fields. They hold the settings made for the playlist in `Settings > Playlists > Manage Playlists`, and all of them can be left out of a hand-made playlist:
+
+| Field | Meaning |
+|---|---|
+| `default_core_path`, `default_core_name` | The playlist's default core, used for entries whose core is `DETECT` or cannot be found. |
+| `label_display_mode` | How entry labels are shortened, for example with the text in brackets removed. |
+| `right_thumbnail_mode`, `left_thumbnail_mode` | Which thumbnails are shown for the playlist, if not the default ones. |
+| `thumbnail_match_mode` | Whether thumbnails are matched by label or by file name. |
+| `sort_mode` | How the entries are sorted. |
+| `base_content_directory` | The content directory the paths were written against, see [Portable playlists](#portable-playlists). |
+| `scan_*` | The settings of the manual scan that made the playlist, used by `Refresh Playlist`. |
+
+Each entry in `items` has:
+
+| Field | Meaning |
+|---|---|
+| `path` | Full path to the content. A file inside an archive is written as `archive.zip#file.ext`. |
+| `label` | The name shown in the menu, which is also used to find thumbnails. |
+| `core_path`, `core_name` | The core to run the entry with, or `DETECT` to use the playlist's default core or to ask. |
+| `crc32` | The content's CRC32 followed by `|crc`, or its serial followed by `|serial`, or `DETECT`. |
+| `db_name` | The database playlist the entry belongs to, such as `Nintendo - Game Boy.lpl`. It picks the thumbnails and the icon. |
+
+Other fields, such as `entry_slot`, the `subsystem_*` fields and the play time fields of the history playlist, are written by RetroArch and can be left out.
+
+### Portable playlists
+
+Playlists hold full paths, so a playlist copied to another device, or to another folder layout, points at files that are not there. **Portable Playlists** in `Settings > Playlists` fixes that:
+
+1. On every device, set `Settings > Directory > File Browser` to the folder that holds your content, for example `/storage/emulated/0/ROMs` on one and `D:\ROMs` on another, and turn on **Portable Playlists**.
+2. Playlists saved with the option on record that folder as `base_content_directory`.
+3. When such a playlist is loaded on a device whose **File Browser** folder is different, RetroArch replaces the recorded folder at the start of each entry's path with its own, converts the slashes for the platform, and saves the corrected playlist.
+
+The content has to sit in the same layout under the **File Browser** folder on every device. Only content paths are rewritten, not core paths: a core is found by its file name, so an entry keeps working wherever the same core is installed. If it is not installed, the playlist's default core is used if one is set, and RetroArch says so.
+
 ### 6-Line Playlist Format (Deprecated)
 
 !!! Warning
@@ -260,6 +296,15 @@ __About "Syncing."__ Contribution work involves changing your copy of the projec
 
 RetroArch retrieves thumbnails from a server (https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before users will see new image contributions in RetroArch playlists.
 
+## Playlist icons
+
+The XMB menu draws each playlist with an icon from the current theme's `png` folder in the assets directory, for example `assets/xmb/monochrome/png/`. The icon file is named after the playlist:
+
+- `<playlist name>.png` is the icon for the playlist itself, for example `Nintendo - Game Boy.png` for `Nintendo - Game Boy.lpl`.
+- `<playlist name>-content.png` is the icon shown next to each of its entries, for example `Nintendo - Game Boy-content.png`.
+
+When a playlist has no icon of its own, `default.png` and `default-content.png` are used. A custom playlist gets its own icons by adding files with its name to the theme's `png` folder.
+
 ## Custom icons/logos for playlist items
 RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file format and subfolder structure follows the same pattern as [custom thumbnails](#custom-thumbnails):
 

docs/guides/turbo-fire.md

@@ -0,0 +1,41 @@
+# Turbo Fire
+
+Turbo Fire makes RetroArch press and release a button over and over while you hold it, for games that expect you to hammer a fire button. It works with every core, whether or not the core has turbo buttons of its own.
+
+The settings are in `Settings > Input > Turbo Fire`. Turbo Fire itself is on by default, but nothing happens until a **Turbo** button is assigned.
+
+## Assigning the Turbo button
+
+Turbo Fire needs a button that switches it on. Assign it in one of two places:
+
+- `Settings > Input > Port 1 Controls > Turbo Fire` (and so on for each port) assigns it for that port only.
+- **Turbo Bind** in `Settings > Input > Turbo Fire` picks one RetroPad button to be the Turbo button on every port. Left empty, the per-port binding above is used.
+
+A RetroPad button set as **Turbo Bind** is not passed to the core as itself while it is pressed.
+
+## Turbo Mode
+
+**Turbo Mode** decides how the Turbo button and the other buttons work together.
+
+| Mode | How to use it |
+|---|---|
+| **Classic** (default) | Hold a button and press the Turbo button: that button fires repeatedly for as long as you keep holding it. Release it and turbo stops. |
+| **Classic (Toggle)** | Hold a button and press the Turbo button once: turbo stays on for that button, which now fires repeatedly whenever you hold it. Hold it and press the Turbo button again to switch turbo off. |
+| **Single Button (Toggle)** | Press the Turbo button once: the button chosen in **Turbo Button** fires repeatedly, without being held. Press the Turbo button again to stop. |
+| **Single Button (Hold)** | The button chosen in **Turbo Button** fires repeatedly while the Turbo button is held down. |
+
+In the two Single Button modes only the button chosen in **Turbo Button** (B by default) can fire. To get the autofire of home computer joysticks, choose **Single Button (Hold)** and set **Turbo Bind** and **Turbo Button** to the same fire button: holding it then fires repeatedly.
+
+## Speed
+
+Turbo presses and releases the button in a repeating cycle:
+
+- **Turbo Period** is the length of one cycle, in frames. The default is 6: at 60 frames per second, 10 presses a second.
+- **Turbo Duty Cycle** is how many frames of each cycle the button is held down. The default, **Half Period**, holds it for half the cycle. A duty cycle equal to or longer than the period never releases the button.
+
+Some games only count a press if the button stays down or up for a few frames. If turbo does not register, make **Turbo Period** longer.
+
+## Other settings
+
+- **Turbo Allow D-Pad Directions** lets the D-pad directions be turbo in the Classic modes. It is off by default, so holding the Turbo button does not turn directions into turbo.
+- **Turbo Fire** switches the whole feature off or on. The `Turbo Fire (Toggle)` hotkey in `Settings > Input > Hotkeys` does the same while playing.

mkdocs.yml

@@ -52,6 +52,7 @@ nav:
     - 'User Guides':
       - 'User Interface': 'guides/navigating.md'
       - 'Input and Controls': 'guides/input-and-controls.md'
+      - 'Turbo Fire': 'guides/turbo-fire.md'
       - 'Starting a Game': 'guides/starting-a-game.md'
       - 'Controller Auto-Configuration': 'guides/controller-autoconfiguration.md'
       - 'Installing Cores': 'guides/download-cores.md'
@@ -74,6 +75,7 @@ nav:
         - 'Multiple Controllers': 'guides/netplay-multiple-controllers.md'
       - 'RetroAchievements': 'guides/retroachievements.md'
       - 'Memory Monitoring': 'guides/memorymonitoring.md'
+      - 'Disc Images: CUE, CHD and M3U': 'guides/disc-images.md'
       - 'Disc Swapping': 'guides/disc-swapping.md'
       - 'Softpatching ROMs': 'guides/softpatching.md'
       - 'Accessibility':