Use the YouTube Data API v3—not browser automation—to rotate playlist entries from a Linux script. First choose whether you are reordering existing videos, replacing an entry, or matching the playlist to a maintained list. Then authorize the script with OAuth, read the full playlist, calculate the change, and apply only the mutations needed. An API key alone cannot make playlist changes.
Choose what “rotation” means
YouTube’s API provides operations for listing, inserting, updating, and deleting playlist entries; it does not supply a single built-in rotation mode. Choose the policy before writing the mutation logic.
| Policy | What changes | What you must decide |
|---|---|---|
| Reorder existing entries | Order changes; membership stays the same. | The cyclic order and which entry moves to which position. The playlist must use manual ordering to set explicit positions. |
| Rolling replacement | One or more entries are removed and new videos inserted. | Which entry is removed, how the incoming video is selected, and whether the playlist should stay a fixed size. |
| Rebuild from a source list | Membership and possibly order are reconciled to a list you maintain. | Which video IDs belong in the desired playlist and how to handle entries absent from that list. |
The right policy depends on the channel: a documentary queue may prioritize a planned sequence, while a rolling playlist may always need the newest uploads. Decide how repeat runs and partial failures should behave before allowing the script to mutate the playlist.
What you need before scripting
- A Google API project with YouTube Data API v3 enabled and OAuth set up for the account that can edit the playlist. Mutating playlist calls require OAuth authorization; an API key by itself is insufficient. See Google’s YouTube Data API reference.
- The target playlist ID and, for additions, the ID of each source video.
- A Linux environment where you can run the script and the scheduler you choose.
- A private way to supply OAuth credentials. Do not put a client secret or refresh token in a public repository or publish it in the script. Google’s API documentation establishes the OAuth requirement, but does not prescribe a Linux secret-storage recipe.
How playlist and video IDs differ
A playlist entry is a playlistItem resource: it represents a video’s placement in a playlist. Its API id identifies that entry, while snippet.resourceId.videoId identifies the video itself. Updates and deletes target the playlist-item ID; insert requests use the video ID. Deleting a playlist item removes that placement, not the underlying video. Google explains the distinction in its playlist implementation guide and playlistItems reference.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Build a safe rotation workflow
- Set up OAuth. Configure the API project and authorize the account that owns or can edit the playlist. Keep secrets out of source control and logs.
- Identify the playlist. Store the playlist ID in private configuration. To discover playlists for the authorized account, Google’s guide uses
playlists.listwithmine=true, which requires OAuth. - Read every page of playlist items. Call
playlistItems.listfor the playlist and follow pagination until the full result is retrieved. For each entry, retain its playlist-itemid, video ID, and current position separately. - Calculate the desired state locally. Apply your chosen policy to the complete current list. Compare current and desired states, and skip mutations that are already satisfied. This makes repeat runs safer; it is your script’s logic, not a YouTube-provided rotation feature.
- Validate the plan before changing anything. Check that the target playlist and source video IDs are present, that the proposed order or membership follows your policy, and that any required explicit positions are valid.
- Apply one mutation at a time and stop on unexpected errors. Log the operation and result without logging credentials. Do not continue making changes after an unexpected failure.
- Fetch the playlist again. Compare the resulting membership and order with the desired state. This verification helps detect partial completion; the API workflow should not be treated as an atomic transaction.
- Schedule only after manual runs work. Run the script under the Linux scheduler appropriate to your distribution and environment. The API references do not establish a cron or systemd recipe, so check your system’s scheduler documentation for exact syntax and execution environment.
Reordering entries
For a cyclic reorder, derive the next order from the full current list—for example, move the first entry to the end—and update only entries whose positions differ. To explicitly set an entry’s position, the playlist must be manually ordered. Otherwise, YouTube can return manualSortRequired; change the playlist’s ordering setting before relying on position updates.
An update request needs the playlist-item ID, playlist ID, video resource ID, and target position. Positions are zero-based: Google’s API example uses 0 for the first entry. Keep the update body limited and complete for the selected part. Google cautions that mutable properties included in the requested part can be overwritten, and omitting an already populated property from that part can delete its value. Consult the playlistItems reference for the current resource fields and update requirements.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Replacing or reconciling entries
Rolling replacement
Identify the exact playlist-item ID that your policy says to remove, then delete that entry and insert the selected video. Decide whether to delete first or insert first based on your tolerance for a temporary size change and the playlist’s item limit; either sequence can leave a partial result if the second request fails. Record the planned operation and re-fetch the playlist after each run.
Reconcile to a maintained list
Keep a source of truth outside YouTube, such as a text file of desired video IDs. Compare it with the complete set of current playlist entries, then insert missing IDs and delete only entries your policy explicitly marks as unwanted. If the desired list also specifies sequence, set positions only when the playlist is manually ordered. Test the computed difference before enabling scheduled mutations.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
The API uses playlistItems.insert, playlistItems.update, and playlistItems.delete for these changes. See the official playlist implementation guide for examples and the insert method reference for insertion requirements.
Errors and recovery
- Authorization or access failure: confirm the OAuth flow used the account that can edit the playlist and that the request has authorization. An API key alone does not grant mutation access; inaccessible items can produce
playlistItemsNotAccessible. - Playlist or video not found: check that the stored playlist ID and source video ID are correct and that the authenticated account can access them.
manualSortRequired: the playlist is not manually ordered, so an explicit position cannot be applied as requested. Change the playlist ordering setting or choose a policy that does not depend on explicit ordering.- Invalid position: check the zero-based target index against the playlist’s current and planned entries, then recompute the plan from a fresh list.
- Playlist at its item limit: an insertion may fail when the playlist has reached its limit. Recheck the current entries and your remove/insert policy rather than blindly retrying.
- Unsupported operation or other API error: stop the run, preserve the error details without secrets, fetch current state, and recalculate before retrying. Do not assume an earlier request in the run was rolled back.
- Unexpected loss of playlist metadata: review the update request’s selected
partand body. Include the mutable properties required for that part, as the API warns that omitted existing values may be cleared.
Google documents relevant authorization, accessibility, missing-resource, unsupported-operation, size-limit, invalid-position, and ordering errors in its API reference and insert method reference.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Schedule and operate it carefully
Keep the scheduler’s configuration separate from rotation policy. Use a predictable working directory, ensure the process can access its OAuth credentials, and capture exit status and useful error output. First run the script manually with a small, reversible change. Then schedule it at an interval that matches how often your source list changes, and verify a scheduled run by checking the playlist and logs. Exact scheduler commands depend on the Linux distribution and environment; consult the matching cron or systemd documentation rather than assuming one command works everywhere.
Or let it run in the cloud
If your goal is to keep uploaded documentaries playing as a 24/7 YouTube live stream, rather than rotate playlist entries through the API, StreamNeo is a separate cloud option: upload your video or build a playlist, add your YouTube stream key, and go live. Nothing has to stay on at home; it streams the uploaded file as made, up to 4K 60fps, at one price per slot; and it automatically recovers if YouTube drops the stream. The first day is free with no card. Monthly pricing is $9.99 per month. StreamNeo streams to YouTube only and does not replace a shell script for changing playlist membership or order. Start at StreamNeo’s free trial.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteQuick Recap
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
