Add --audio-output-buffer

On some systems, the SDL audio callback is not called frequently enough
(for example it requests 5ms of samples every 10ms), because the output
buffer is too small.

By default, we want to use a small value (5ms) to minimize latency, but
if it does not work well, users need a way to increase it.

Refs #3793 <https://github.com/Genymobile/scrcpy/issues/3793>

README.md

@@ -35,15 +35,15 @@ Its features include:
  - [OTG mode](doc/hid-otg.md#otg)
  - and more…
 
-## Requirements
+## Prerequisites
 
 The Android device requires at least API 21 (Android 5.0).
 
 [Audio forwarding](doc/audio.md) is supported from API 30 (Android 11).
 
-Make sure you [enabled adb debugging][enable-adb] on your device(s).
+Make sure you [enabled USB debugging][enable-adb] on your device(s).
 
-[enable-adb]: https://developer.android.com/studio/command-line/adb.html#Enabling
+[enable-adb]: https://developer.android.com/studio/debug/dev-options#enable
 
 On some devices, you also need to enable [an additional option][control] `USB
 debugging (Security Settings)` (this is an item different from `USB debugging`)
@@ -90,10 +90,11 @@ documented in the following pages:
 
 - [Introducing scrcpy][article-intro]
 - [Scrcpy now works wirelessly][article-tcpip]
+- [Scrcpy 2.0, with audio][article-scrcpy2]
 
 [article-intro]: https://blog.rom1v.com/2018/03/introducing-scrcpy/
 [article-tcpip]: https://www.genymotion.com/blog/open-source-project-scrcpy-now-works-wirelessly/
-
+[article-scrcpy2]: https://blog.rom1v.com/2023/03/scrcpy-2-0-with-audio/
 
 ## Contact
 

app/data/scrcpy-console.desktop

@@ -5,7 +5,7 @@ Comment=Display and control your Android device
 # For some users, the PATH or ADB environment variables are set from the shell
 # startup file, like .bashrc or .zshrc… Run an interactive shell to get
 # environment correctly initialized.
-Exec=/bin/bash --norc --noprofile -i -c '"$SHELL" -i -c scrcpy || read -p "Press any key to quit..."'
+Exec=/bin/bash --norc --noprofile -i -c "\"\\$SHELL\" -i -c scrcpy || read -p 'Press any key to quit...'"
 Icon=scrcpy
 Terminal=true
 Type=Application

app/data/scrcpy.desktop

@@ -5,7 +5,7 @@ Comment=Display and control your Android device
 # For some users, the PATH or ADB environment variables are set from the shell
 # startup file, like .bashrc or .zshrc… Run an interactive shell to get
 # environment correctly initialized.
-Exec=/bin/sh -c '"$SHELL" -i -c scrcpy'
+Exec=/bin/sh -c "\"\\$SHELL\" -i -c scrcpy"
 Icon=scrcpy
 Terminal=false
 Type=Application

app/scrcpy.1

@@ -33,6 +33,14 @@ Lower values decrease the latency, but increase the likelyhood of buffer underru
 
 Default is 50.
 
+.TP
+.BI "\-\-audio\-output\-buffer ms
+Configure the size of the SDL audio output buffer (in milliseconds).
+
+If you get "robotic" audio playback, you should test with a higher value (10). Do not change this setting otherwise.
+
+Default is 5.
+
 .TP
 .BI "\-\-audio\-codec " name
 Select an audio codec (opus, aac or raw).

app/src/audio_player.c

@@ -59,8 +59,6 @@
 #define SC_AV_SAMPLE_FMT AV_SAMPLE_FMT_FLT
 #define SC_SDL_SAMPLE_FMT AUDIO_F32
 
-#define SC_AUDIO_OUTPUT_BUFFER_MS 5
-
 #define TO_BYTES(SAMPLES) sc_audiobuf_to_bytes(&ap->buf, (SAMPLES))
 #define TO_SAMPLES(BYTES) sc_audiobuf_to_samples(&ap->buf, (BYTES))
 
@@ -230,8 +228,8 @@ sc_audio_player_frame_sink_push(struct sc_frame_sink *sink,
 
     if (played) {
         uint32_t max_buffered_samples = ap->target_buffering
-                + 12 * SC_AUDIO_OUTPUT_BUFFER_MS * ap->sample_rate / 1000
-                + ap->target_buffering / 10;
+                                      + 12 * ap->output_buffer
+                                      + ap->target_buffering / 10;
         if (buffered_samples > max_buffered_samples) {
             uint32_t skip_samples = buffered_samples - max_buffered_samples;
             sc_audiobuf_skip(&ap->buf, skip_samples);
@@ -246,7 +244,7 @@ sc_audio_player_frame_sink_push(struct sc_frame_sink *sink,
         // max_initial_buffering samples, this would cause unnecessary delay
         // (and glitches to compensate) on start.
         uint32_t max_initial_buffering = ap->target_buffering
-                + 2 * SC_AUDIO_OUTPUT_BUFFER_MS * ap->sample_rate / 1000;
+                                       + 2 * ap->output_buffer;
         if (buffered_samples > max_initial_buffering) {
             uint32_t skip_samples = buffered_samples - max_initial_buffering;
             sc_audiobuf_skip(&ap->buf, skip_samples);
@@ -287,7 +285,7 @@ sc_audio_player_frame_sink_push(struct sc_frame_sink *sink,
 
             float avg = sc_average_get(&ap->avg_buffering);
             int diff = ap->target_buffering - avg;
-            if (abs(diff) < ap->sample_rate / 1000) {
+            if (abs(diff) < (int) ap->sample_rate / 1000) {
                 // Do not compensate for less than 1ms, the error is just noise
                 diff = 0;
             } else if (diff < 0 && buffered_samples < ap->target_buffering) {
@@ -333,11 +331,28 @@ sc_audio_player_frame_sink_open(struct sc_frame_sink *sink,
     unsigned nb_channels = tmp;
 #endif
 
+    assert(ctx->sample_rate > 0);
+    assert(!av_sample_fmt_is_planar(SC_AV_SAMPLE_FMT));
+    int out_bytes_per_sample = av_get_bytes_per_sample(SC_AV_SAMPLE_FMT);
+    assert(out_bytes_per_sample > 0);
+
+    ap->sample_rate = ctx->sample_rate;
+    ap->nb_channels = nb_channels;
+    ap->out_bytes_per_sample = out_bytes_per_sample;
+
+    ap->target_buffering = ap->target_buffering_delay * ap->sample_rate
+                                                      / SC_TICK_FREQ;
+
+    uint64_t aout_samples = ap->output_buffer_duration * ap->sample_rate
+                                                       / SC_TICK_FREQ;
+    assert(aout_samples <= 0xFFFF);
+    ap->output_buffer = (uint16_t) aout_samples;
+
     SDL_AudioSpec desired = {
         .freq = ctx->sample_rate,
         .format = SC_SDL_SAMPLE_FMT,
         .channels = nb_channels,
-        .samples = SC_AUDIO_OUTPUT_BUFFER_MS * ctx->sample_rate / 1000,
+        .samples = aout_samples,
         .callback = sc_audio_player_sdl_callback,
         .userdata = ap,
     };
@@ -356,11 +371,6 @@ sc_audio_player_frame_sink_open(struct sc_frame_sink *sink,
     }
     ap->swr_ctx = swr_ctx;
 
-    assert(ctx->sample_rate > 0);
-    assert(!av_sample_fmt_is_planar(SC_AV_SAMPLE_FMT));
-    int out_bytes_per_sample = av_get_bytes_per_sample(SC_AV_SAMPLE_FMT);
-    assert(out_bytes_per_sample > 0);
-
 #ifdef SCRCPY_LAVU_HAS_CHLAYOUT
     av_opt_set_chlayout(swr_ctx, "in_chlayout", &ctx->ch_layout, 0);
     av_opt_set_chlayout(swr_ctx, "out_chlayout", &ctx->ch_layout, 0);
@@ -383,13 +393,6 @@ sc_audio_player_frame_sink_open(struct sc_frame_sink *sink,
         goto error_free_swr_ctx;
     }
 
-    ap->sample_rate = ctx->sample_rate;
-    ap->nb_channels = nb_channels;
-    ap->out_bytes_per_sample = out_bytes_per_sample;
-
-    ap->target_buffering = ap->target_buffering_delay * ap->sample_rate
-                                                      / SC_TICK_FREQ;
-
     // Use a ring-buffer of the target buffering size plus 1 second between the
     // producer and the consumer. It's too big on purpose, to guarantee that
     // the producer and the consumer will be able to access it in parallel
@@ -458,8 +461,10 @@ sc_audio_player_frame_sink_close(struct sc_frame_sink *sink) {
 }
 
 void
-sc_audio_player_init(struct sc_audio_player *ap, sc_tick target_buffering) {
+sc_audio_player_init(struct sc_audio_player *ap, sc_tick target_buffering,
+                     sc_tick output_buffer_duration) {
     ap->target_buffering_delay = target_buffering;
+    ap->output_buffer_duration = output_buffer_duration;
 
     static const struct sc_frame_sink_ops ops = {
         .open = sc_audio_player_frame_sink_open,

app/src/audio_player.h

@@ -27,6 +27,10 @@ struct sc_audio_player {
     sc_tick target_buffering_delay;
     uint32_t target_buffering; // in samples
 
+    // SDL audio output buffer size.
+    sc_tick output_buffer_duration;
+    uint16_t output_buffer;
+
     // Audio buffer to communicate between the receiver and the SDL audio
     // callback (protected by SDL_AudioDeviceLock())
     struct sc_audiobuf buf;
@@ -80,6 +84,7 @@ struct sc_audio_player_callbacks {
 };
 
 void
-sc_audio_player_init(struct sc_audio_player *ap, sc_tick target_buffering);
+sc_audio_player_init(struct sc_audio_player *ap, sc_tick target_buffering,
+                     sc_tick audio_output_buffer);
 
 #endif

app/src/cli.c

@@ -71,6 +71,7 @@ enum {
     OPT_LIST_DISPLAYS,
     OPT_REQUIRE_AUDIO,
     OPT_AUDIO_BUFFER,
+    OPT_AUDIO_OUTPUT_BUFFER,
 };
 
 struct sc_option {
@@ -129,6 +130,16 @@ static const struct sc_option options[] = {
                 "likelyhood of buffer underrun (causing audio glitches).\n"
                 "Default is 50.",
     },
+    {
+        .longopt_id = OPT_AUDIO_OUTPUT_BUFFER,
+        .longopt = "audio-output-buffer",
+        .argdesc = "ms",
+        .text = "Configure the size of the SDL audio output buffer (in "
+                "milliseconds).\n"
+                "If you get \"robotic\" audio playback, you should test with "
+                "a higher value (10). Do not change this setting otherwise.\n"
+                "Default is 5.",
+    },
     {
         .longopt_id = OPT_AUDIO_CODEC,
         .longopt = "audio-codec",
@@ -1204,6 +1215,19 @@ parse_buffering_time(const char *s, sc_tick *tick) {
     return true;
 }
 
+static bool
+parse_audio_output_buffer(const char *s, sc_tick *tick) {
+    long value;
+    bool ok = parse_integer_arg(s, &value, false, 0, 1000,
+                                "audio output buffer");
+    if (!ok) {
+        return false;
+    }
+
+    *tick = SC_TICK_FROM_MS(value);
+    return true;
+}
+
 static bool
 parse_lock_video_orientation(const char *s,
                              enum sc_lock_video_orientation *lock_mode) {
@@ -1831,6 +1855,12 @@ parse_args_with_getopt(struct scrcpy_cli_args *args, int argc, char *argv[],
                     return false;
                 }
                 break;
+            case OPT_AUDIO_OUTPUT_BUFFER:
+                if (!parse_audio_output_buffer(optarg,
+                                               &opts->audio_output_buffer)) {
+                    return false;
+                }
+                break;
             default:
                 // getopt prints the error message on stderr
                 return false;

app/src/demuxer.c

@@ -1,6 +1,7 @@
 #include "demuxer.h"
 
 #include <assert.h>
+#include <libavutil/channel_layout.h>
 #include <libavutil/time.h>
 #include <unistd.h>
 

app/src/options.c

@@ -44,6 +44,7 @@ const struct scrcpy_options scrcpy_options_default = {
     .display_buffer = 0,
     .v4l2_buffer = 0,
     .audio_buffer = SC_TICK_FROM_MS(50),
+    .audio_output_buffer = SC_TICK_FROM_MS(5),
 #ifdef HAVE_USB
     .otg = false,
 #endif

app/src/options.h

@@ -127,6 +127,7 @@ struct scrcpy_options {
     sc_tick display_buffer;
     sc_tick v4l2_buffer;
     sc_tick audio_buffer;
+    sc_tick audio_output_buffer;
 #ifdef HAVE_USB
     bool otg;
 #endif

app/src/scrcpy.c

@@ -688,7 +688,8 @@ aoa_hid_end:
         sc_frame_source_add_sink(src, &s->screen.frame_sink);
 
         if (options->audio) {
-            sc_audio_player_init(&s->audio_player, options->audio_buffer);
+            sc_audio_player_init(&s->audio_player, options->audio_buffer,
+                                 options->audio_output_buffer);
             sc_frame_source_add_sink(&s->audio_decoder.frame_source,
                                      &s->audio_player.frame_sink);
         }

app/src/screen.c

@@ -816,7 +816,7 @@ sc_screen_handle_event(struct sc_screen *screen, SDL_Event *event) {
     bool relative_mode = sc_screen_is_relative_mode(screen);
 
     switch (event->type) {
-        case SC_EVENT_SCREEN_INIT_SIZE:
+        case SC_EVENT_SCREEN_INIT_SIZE: {
             // The initial size is passed via screen->frame_size
             bool ok = sc_screen_init_size(screen);
             if (!ok) {
@@ -824,6 +824,7 @@ sc_screen_handle_event(struct sc_screen *screen, SDL_Event *event) {
                 return false;
             }
             return true;
+        }
         case SC_EVENT_NEW_FRAME: {
             bool ok = sc_screen_update_frame(screen);
             if (!ok) {

app/src/v4l2_sink.c

@@ -210,6 +210,9 @@ sc_v4l2_sink_open(struct sc_v4l2_sink *vs, const AVCodecContext *ctx) {
         goto error_avformat_free_context;
     }
 
+    // The codec is from the v4l2 encoder, not from the decoder
+    ostream->codecpar->codec_id = encoder->id;
+
     int ret = avio_open(&vs->format_ctx->pb, vs->device_name, AVIO_FLAG_WRITE);
     if (ret < 0) {
         LOGE("Failed to open output device: %s", vs->device_name);

doc/audio.md

@@ -88,3 +88,14 @@ avoid glitches and smooth the playback:
 ```
 scrcpy --display-buffer=200 --audio-buffer=200
 ```
+
+It is also possible to configure another audio buffer (the audio output buffer),
+by default set to 5ms. Don't change it, unless you get some [robotic and glitchy
+sound][#3793]:
+
+```bash
+# Only if absolutely necessary
+scrcpy --audio-output-buffer=10
+```
+
+[#3793]: https://github.com/Genymobile/scrcpy/issues/3793

doc/device.md

@@ -107,10 +107,10 @@ with the device IP address you found)_.
 7. Run `scrcpy` as usual.
 8. Run `adb disconnect` once you're done.
 
-Since Android 11, a [Wireless debugging option][adb-wireless] allows to bypass
+Since Android 11, a [wireless debugging option][adb-wireless] allows to bypass
 having to physically connect your device directly to your computer.
 
-[adb-wireless]: https://developer.android.com/studio/command-line/adb#connect-to-a-device-over-wi-fi-android-11+
+[adb-wireless]: https://developer.android.com/studio/command-line/adb#wireless-android11-command-line
 
 
 ## Autostart

doc/linux.md

@@ -61,6 +61,8 @@ _See [build.md](build.md) to build and install the app manually._
 
 ## Run
 
+_Make sure that your device meets the [prerequisites](/README.md#prerequisites)._
+
 Once installed, run from a terminal:
 
 ```bash

doc/macos.md

@@ -29,6 +29,8 @@ _See [build.md](build.md) to build and install the app manually._
 
 ## Run
 
+_Make sure that your device meets the [prerequisites](/README.md#prerequisites)._
+
 Once installed, run from a terminal:
 
 ```bash

doc/shortcuts.md

@@ -49,7 +49,7 @@ _<kbd>[Super]</kbd> is typically the <kbd>Windows</kbd> or <kbd>Cmd</kbd> key._
  | Enable/disable FPS counter (on stdout)      | <kbd>MOD</kbd>+<kbd>i</kbd>
  | Pinch-to-zoom                               | <kbd>Ctrl</kbd>+_click-and-move_
  | Drag & drop APK file                        | Install APK from computer
- | Drag & drop non-APK file                    | [Push file to device](#push-file-to-device)
+ | Drag & drop non-APK file                    | [Push file to device](control.md#push-file-to-device)
 
 _¹Double-click on black borders to remove them._  
 _²Right-click turns the screen on if it was off, presses BACK otherwise._  

doc/windows.md

@@ -9,7 +9,7 @@ Download the [latest release]:
  - [`scrcpy-win32-v2.0.zip`][direct-win32] (32-bit)  
    <sub>SHA-256: `15d98c02cb0e0bbd84f8b5d54991e0f6925569b1286a86a40743944fcb1c2d8c`</sub>
 
-[release]: https://github.com/Genymobile/scrcpy/releases/latest
+[latest release]: https://github.com/Genymobile/scrcpy/releases/latest
 [direct-win64]: https://github.com/Genymobile/scrcpy/releases/download/v2.0/scrcpy-win64-v2.0.zip
 [direct-win32]: https://github.com/Genymobile/scrcpy/releases/download/v2.0/scrcpy-win32-v2.0.zip
 
@@ -38,6 +38,8 @@ _See [build.md](build.md) to build and install the app manually._
 
 ## Run
 
+_Make sure that your device meets the [prerequisites](/README.md#prerequisites)._
+
 Scrcpy is a command line application: it is mainly intended to be executed from
 a terminal with command line arguments.
 

server/src/main/java/com/genymobile/scrcpy/AudioCapture.java

@@ -111,7 +111,7 @@ public final class AudioCapture {
     @TargetApi(Build.VERSION_CODES.N)
     public int read(ByteBuffer directBuffer, int size, MediaCodec.BufferInfo outBufferInfo) {
         int r = recorder.read(directBuffer, size);
-        if (r < 0) {
+        if (r <= 0) {
             return r;
         }
 

server/src/main/java/com/genymobile/scrcpy/AudioEncoder.java

@@ -92,7 +92,7 @@ public final class AudioEncoder implements AsyncProcessor {
             InputTask task = inputTasks.take();
             ByteBuffer buffer = mediaCodec.getInputBuffer(task.index);
             int r = capture.read(buffer, READ_SIZE, bufferInfo);
-            if (r < 0) {
+            if (r <= 0) {
                 throw new IOException("Could not read audio: " + r);
             }
 

server/src/main/java/com/genymobile/scrcpy/Server.java

@@ -81,15 +81,15 @@ public final class Server {
         // But only apply when strictly necessary, since workarounds can cause other issues:
         //  - <https://github.com/Genymobile/scrcpy/issues/940>
         //  - <https://github.com/Genymobile/scrcpy/issues/994>
-        boolean mustFillAppInfo = Build.BRAND.equalsIgnoreCase("meizu");
+        if (Build.BRAND.equalsIgnoreCase("meizu")) {
+            Workarounds.fillAppInfo();
+        }
 
         // Before Android 11, audio is not supported.
         // Since Android 12, we can properly set a context on the AudioRecord.
-        // Only on Android 11 we must fill app info for the AudioRecord to work.
-        mustFillAppInfo |= audio && Build.VERSION.SDK_INT == Build.VERSION_CODES.R;
-
-        if (mustFillAppInfo) {
-            Workarounds.fillAppInfo();
+        // Only on Android 11 we must fill the application context for the AudioRecord to work.
+        if (audio && Build.VERSION.SDK_INT == Build.VERSION_CODES.R) {
+            Workarounds.fillAppContext();
         }
 
         List<AsyncProcessor> asyncProcessors = new ArrayList<>();

server/src/main/java/com/genymobile/scrcpy/Workarounds.java

@@ -10,6 +10,10 @@ import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
 
 public final class Workarounds {
+
+    private static Class<?> activityThreadClass;
+    private static Object activityThread;
+
     private Workarounds() {
         // not instantiable
     }
@@ -28,18 +32,25 @@ public final class Workarounds {
     }
 
     @SuppressLint("PrivateApi,DiscouragedPrivateApi")
-    public static void fillAppInfo() {
-        try {
+    private static void fillActivityThread() throws Exception {
+        if (activityThread == null) {
             // ActivityThread activityThread = new ActivityThread();
-            Class<?> activityThreadClass = Class.forName("android.app.ActivityThread");
+            activityThreadClass = Class.forName("android.app.ActivityThread");
             Constructor<?> activityThreadConstructor = activityThreadClass.getDeclaredConstructor();
             activityThreadConstructor.setAccessible(true);
-            Object activityThread = activityThreadConstructor.newInstance();
+            activityThread = activityThreadConstructor.newInstance();
 
             // ActivityThread.sCurrentActivityThread = activityThread;
             Field sCurrentActivityThreadField = activityThreadClass.getDeclaredField("sCurrentActivityThread");
             sCurrentActivityThreadField.setAccessible(true);
             sCurrentActivityThreadField.set(null, activityThread);
+        }
+    }
+
+    @SuppressLint("PrivateApi,DiscouragedPrivateApi")
+    public static void fillAppInfo() {
+        try {
+            fillActivityThread();
 
             // ActivityThread.AppBindData appBindData = new ActivityThread.AppBindData();
             Class<?> appBindDataClass = Class.forName("android.app.ActivityThread$AppBindData");
@@ -59,6 +70,16 @@ public final class Workarounds {
             Field mBoundApplicationField = activityThreadClass.getDeclaredField("mBoundApplication");
             mBoundApplicationField.setAccessible(true);
             mBoundApplicationField.set(activityThread, appBindData);
+        } catch (Throwable throwable) {
+            // this is a workaround, so failing is not an error
+            Ln.d("Could not fill app info: " + throwable.getMessage());
+        }
+    }
+
+    @SuppressLint("PrivateApi,DiscouragedPrivateApi")
+    public static void fillAppContext() {
+        try {
+            fillActivityThread();
 
             Application app = Application.class.newInstance();
             Field baseField = ContextWrapper.class.getDeclaredField("mBase");
@@ -71,7 +92,7 @@ public final class Workarounds {
             mInitialApplicationField.set(activityThread, app);
         } catch (Throwable throwable) {
             // this is a workaround, so failing is not an error
-            Ln.d("Could not fill app info: " + throwable.getMessage());
+            Ln.d("Could not fill app context: " + throwable.getMessage());
         }
     }
 }