screenrecord
會改變裝置把螢幕錄成裝置上的一個 MP4 檔。
- 指令
- adb shell screenrecord
- 指令
- 畫面與擷取
- 風險
- 會改變裝置
語法
screenrecord [--size <width>x<height>] [--bit-rate <bps>] [--time-limit <seconds>] <device path>旗標與參數
| token | 意義 |
|---|---|
| --time-limit <s> | 到這麼多秒就停。這個執行檔自己的說明寫著預設與最大都是 180。 |
| --bit-rate <bps> | 每秒位元數。說明寫著預設是 20 Mbps。 |
| --size <w>x<h> | 這是一個「要求」而不是保證。說明寫著支援的話預設就是顯示器解析度、不支援則是 1280x720，並建議使用編碼器支援的尺寸。 |
| --bugreport | 在影片上疊一層額外資訊，其中包含時間戳。適合那種必須證明某件事「什麼時候」發生、而不只是發生了什麼的片段。 |
| --display-id <id> | 錄某一個實體顯示器而不是主顯示器。合法的 id 來自 `dumpsys SurfaceFlinger --display-id`；指名一個目前沒開著的顯示器，會得到 layer-stack 錯誤而不是一個檔案。 |
| --verbose | 錄影期間在 stdout 回報進度。第一次遇到片段錄出來是空的時候值得帶上，因為它會告訴你到底有沒有任何一格進到編碼器。 |
範例
screenrecord --time-limit 30 /sdcard/demo.mp4錄 30 秒，然後把檔案拉回來。
screenrecord --bit-rate 8000000 --size 720x1560 /sdcard/small.mp4給錯誤報告用的較小、較省的錄影。
kill -INT $(pidof screenrecord)提早「正確地」停下來——原因見注意事項。
screenrecord --time-limit 0 /sdcard/long.mp4完全不設上限，只有你去中斷它才會停。Android 14 以上才行；13 以下的 0 不在接受範圍內，指令會拒絕。
dumpsys SurfaceFlinger --display-id在瞎猜之前先把顯示器 id 列出來，因為錯的 id 是以 layer-stack 錯誤而不是參數錯誤的形式失敗的。
輸出怎麼讀
執行中什麼都不會印，結束時檔案就出現了。被拒絕（編碼器不接受的尺寸、寫不進去的路徑）是這個執行檔自己印出來的，那段文字就是答案，不是這一頁能預先講出來的東西。
輸出欄位
| 欄位 | 意義 |
|---|---|
| (no output) | 正在錄。檔案會邊錄邊寫。 |
| (an error line) | 裝置自己的拒絕訊息。照原文讀。 |
| Time limit reached | 錄影是自己結束的、不是被什麼東西中斷時，會寫到 stdout。檔案是完整而且有索引的。 |
| WARNING: failed at 1440x3120, retrying at 1280x720 | 編碼器不接受顯示器回報的那個尺寸，於是錄影程式自己降低目標，改試 720p。只有在你「沒有」給 `--size` 的時候它才會這樣做；明確給了尺寸它就會失敗，而不是換一個你沒要求的東西給你。 |
需要什麼權限
一條已授權的 `adb` 連線，其他什麼都不用——不用 root、不用 `adb root`、不用 `su`，開發者選項裡除了 USB 偵錯本身也沒有開關要打開。決定檔案能落在哪裡的，是 `adbd` 用什麼身分跑你的指令：它會降到 `shell` 的 uid 與 gid，並給自己一組固定的附加群組清單（`packages/modules/adb/daemon/main.cpp`），裡面包含 `sdcard_rw`、`ext_data_rw` 與 `ext_obb_rw`。這就是為什麼寫在 `/sdcard/` 底下的錄影不需要爭論就會出現，而同一個指令對著 `/system/` 或另一個 app 的私有目錄，根本連檔案都建不出來。挑目的地的時候把這件事放在心上：`/sdcard/` 與 `/data/local/tmp/` 都可以，唯讀的掛載點不行，而一旦 muxer 自己的 `open()` 失敗，這個執行檔是直接 `abort()` 而不會跟你解釋。有兩種拒絕常被誤認成權限問題，但兩者都不是。受 DRM 保護的畫面錄成全黑，是因為合成器不肯把受保護的緩衝交給任何編碼器——包含 root——所以再高的權限也改變不了這個結果。而要乾淨地停止錄影需要「第二個」shell，因為中斷訊號必須送給一個已經在跑的行程：Android Screen Mirror 那一頁會把第二條通道開著，這正是它的停止按鈕能產出可播放的檔案而不是被截斷的檔案的全部理由。`adb root` 不是這一頁上任何問題的答案；在量產版本上它會被直接拒絕，只有在 `userdebug` 與 `eng` 映像上才會把 `adbd` 以 root 重啟。
失敗訊息對照
| 訊息 | 意義 |
|---|---|
| Must specify output file (see --help). | 參數解析結束後沒有任何檔名活下來，所以什麼都沒錄。這裡每個選項都是長選項，這讓拼錯變得很貴：`--timelimit` 而不是 `--time-limit` 會被當成未知選項吃掉，後面那個數字也跟著被吃掉，於是路徑落到解析器根本走不到的位置。檢查儲存空間之前，先檢查旗標的拼字。 |
| Invalid size '1080', must be width x height | `--size` 要兩個維度用一個字面的 `x` 連起來，其他一律拒絕，並在擷取任何一格之前以結束碼 2 收場。被引回來的那個值就是你的 shell 實際送出去的東西，所以一個因為沒加引號、後半被空白拆掉的尺寸，會在這裡以它的前半出現——把參數加上引號，這種模糊就消失了。 |
| Bit rate 50000bps outside acceptable range [100000,200000000] | 括號裡那一對是寫死在原始碼裡的——下限 0.1 Mbps、上限 200 Mbps——而前面那個數字是你要求的值。`--bit-rate` 除了純粹的位元數之外也接受 `4M` 這種簡寫，而簡寫的單位是 megabit，所以寫成 `4` 等於在要求每秒四個位元，然後換來這一行。 |
| Time limit 300s outside acceptable range [1,180] | Android 13 以下：在那裡 180 秒是硬上限而不只是預設，更長的要求在開始錄之前就被拒絕。Android 14 與 15 對同一個錯誤會印另一行，引的範圍是 `[0,4294967295] seconds`，而且它們把 `0` 當成完全不設上限——所以同一支手機上被 13 拒絕的指令，升級之後可以成功。相信裝置引出來的那個範圍，不要相信從別處記來的數字。 |
| ERROR: INVALID_LAYER_STACK, please check your display state. | 擷取沒辦法綁到某個顯示器的 layer stack，所以錄影程式直接結束，而不是寫出一個裡面什麼都沒有的檔案。螢幕關著的時候會遇到，`--display-id` 指到一個目前沒有啟用的顯示器時也會。先把裝置喚醒，或者拿掉 `--display-id`，讓錄影程式自己拿主顯示器。 |
會改變什麼，以及怎麼回頭
它一定會寫檔：MP4 會存到你指定的裝置路徑，路徑不存在就建立、已經有檔案就覆寫，所以路徑打錯可能蓋掉一個真的檔案，舊內容就沒了。檔案大小隨錄影長度與位元率成長，在你刪掉之前一直占著儲存空間——想留著就先用 `adb pull` 拉到電腦，之後用 `rm <路徑>` 刪除。裝置上其他東西都不會變。
版本與廠商注意事項
- 要用中斷訊號停止，不要用切斷連線的方式。一個 MP4 只有在索引被寫入之後才能播放，而這個執行檔是在收到中斷訊號時的收尾流程裡寫索引的——直接把 socket 拆掉會留下一個被截斷的檔案，有些播放器會完全放不出來。
- 沒有聲音。這個執行檔只錄影像，也沒有聲音的旗標。
- 受 DRM 保護的畫面會錄成全黑，和截圖是全黑的原因相同。
- 影格尺寸在開始錄的時候就固定了，所以錄到一半旋轉手機，後面就會變成加黑邊。
- 180 秒的上限是這個執行檔的性質而不是纜線的限制。哪個版本和它不一致時，相信裝置自己的拒絕訊息，而不是任何文件。
- 那個上限正是各版本真正不一樣的地方。Android 11、12、13 拒絕 `[1,180]` 以外的任何值；Android 14 與 15 接受到 4294967295 秒，並且把 `0` 記載為取消上限，同時預設仍然是 180。拒絕訊息會引出它自己的範圍，而那是唯一值得做的版本檢查。
- 目的地會在很早的時候先被開啟一次，純粹是為了讓錯的路徑失敗得讓人看得懂，訊息裡會有路徑與原因。如果失敗的是後面 muxer 那條路徑上的開啟，訊息就會是光禿禿的 `ERROR: couldn't open file`，裡面沒有路徑——所以一個沒有路徑的失敗，就是一個發生得比較晚的失敗。
這個我們有 UI
Android Screen Mirror 會透過 USB 執行這個指令並解析回應——只要 Chromium 系瀏覽器，不必安裝 SDK，也不會上傳任何東西。
相關指令
和 screenrecord 會在同一次作業裡出現的指令。
其他畫面與擷取指令
| 指令 | 做什麼 |
|---|---|
| wm density | 回報顯示密度，或覆寫它——真正會讓版面斷點移動的是這一個。 |
這些行為是在撰寫 Web ADB 工具背後的解析程式時，對照 AOSP、toybox 與核心原始碼查證的。真的會因 Android 版本或廠牌而異的地方，這一頁會直接說明，而不是給你一個在半數手機上都是錯的數字。