A systemd timer can run a script on a calendar schedule, and that script can make an OAuth-authorised edit to a YouTube playlist through the YouTube Data API. This changes playlist membership or order; it does not change what is currently being sent to a live broadcast.
The practical path is to choose one playlist operation, authorise a script to make it, run that script through a service unit, and let a timer activate the service. Keep each step testable on its own, and decide what should happen if the Linux machine is off at the scheduled time.
How timers and playlist edits fit together
A timer is a trigger, not the editor. In the usual arrangement, a .timer unit activates a .service unit with the same base name. The service runs a script, and the script makes a YouTube Data API request using credentials authorised for the relevant YouTube account. The systemd timer manual describes calendar triggers and the timer's relationship to activated units.
That separation is useful when something goes wrong. You can run the script by hand to test the API request, start the service to test its execution context and logs, and inspect the timer to confirm when it will next activate. A failure in one layer is easier to find than when scheduling, credentials and playlist logic are all mixed into one shell command.
Be precise about what the scheduled edit affects. A playlist item is an entry in a YouTube playlist; it is not the video file being broadcast and it is not the live stream's source. If your channel is playing a video file continuously, changing a playlist through the API does not tell a separate encoder to switch to another file. For a continuous broadcast, the playlist setup for a virtual study room is a useful reference for thinking about playback as a separate concern.
A timer on a home machine also depends on that machine being available, awake and connected. A calendar trigger can be appropriate for a weekly devotional rotation or a daily news-list update, but it cannot run while the host is powered off. You can choose whether a missed calendar event should be caught up later, as described below.
Choose the playlist operation first
Decide whether the task is to add an item, change an existing item, or remove one. These are different playlist-item operations, with different identifiers and data to supply. The YouTube playlist implementation guide explains the resource model and methods.
| Intended change | API operation | Identifier and fields to plan for | Important check |
|---|---|---|---|
| Add a video | playlistItems.insert |
Playlist ID and video ID in the resource details | A requested position requires manual playlist ordering |
| Move an existing entry | playlistItems.update |
Playlist-item ID, playlist ID, video resource details and position | Preserve the mutable values in the selected resource parts |
| Remove an entry | playlistItems.delete |
Playlist-item ID | Do not substitute the video's ID |
To add a video, the script supplies the target playlist and the video resource to insert. If it also specifies a position, the playlist needs manual ordering. If you simply want an item present and do not need to position it, avoid assuming that a playlist with a different ordering mode will honour a requested position. Some system playlists, including the uploaded-videos playlist, do not support these edits; check the API documentation and test against the intended playlist.
Reordering is not a change to a video's position in a live stream. The script first needs to find the relevant playlist item and retain its playlist-item id, then update that item with the desired position. Position is a zero-based index, so the first position is represented as zero. Before writing, confirm that the playlist's ordering mode and your intended index match the result you want.
For deletion, identify the playlist item and delete that item. A video ID identifies the video; a playlist-item ID identifies its occurrence in a particular playlist. The distinction matters if the same video appears more than once, or in several playlists. A safe script should list or otherwise establish the exact entry to remove before calling the delete method.
Prepare OAuth access for the YouTube Data API
Playlist writes require OAuth authorisation. An API key by itself is not the documented authorisation for insert, update or delete operations. The YouTube authentication guide describes the API's OAuth approach; use it alongside the documentation for the exact method your script calls.
For an unattended job, authorise the account that owns or can edit the target playlist, then make the resulting credential available to the service at runtime. The service's Linux user needs permission to read the credential and any configuration it depends on. Keep those files out of a public web directory, source repository and world-readable locations. The sources describe the OAuth requirement, but do not prescribe one universal Linux token-storage or refresh arrangement. Choose one that suits the host and the account, and verify how it behaves after a token expires or needs renewed consent.
Do the first authorisation interactively rather than trying to make the timer perform a login. A scheduled service has no reliable way to answer an account sign-in prompt. Complete the authorised flow, then make a small, reversible test with the same account and playlist that the scheduled job will use. If the account, playlist permissions or OAuth configuration changes, check the credential again rather than treating a successful old test as permanent proof.
Avoid putting access tokens, client secrets or other credentials directly in the unit file or command line. Unit files may be readable by administrators and can appear in diagnostic output. Use a credential file or a suitable secret-handling mechanism for your system, set restrictive permissions, and configure the service explicitly to read it. Do not assume an interactive shell's exported variables will exist when systemd launches the service.
The API reference pages document a quota impact for write methods, but quota rules can change. If you plan frequent edits, check the current method documentation and quota guidance rather than scheduling repeated writes as a substitute for tracking state. A human-scale update, such as replacing a weekly playlist entry, usually benefits more from a clear audit trail than from frequent polling.
Write a script that makes one change safely
Keep the playlist logic in a script that can run independently of systemd. Its configuration should make the intended account context, playlist ID, operation and target video or playlist-item ID explicit. Avoid a script that silently guesses which playlist item to move based only on a title: titles can repeat or change.
For insertion, check whether the desired video is already present before adding it. For removal and reordering, confirm the intended playlist item still exists and still belongs to the expected playlist. These checks are practical safeguards, not API guarantees. They help make repeated or delayed invocations less likely to create duplicate entries or act on stale assumptions.
When updating, pay attention to the fields included in the selected part. The update method writes mutable fields in the parts being updated; values omitted from those parts can be removed. Read the current resource, construct the update with the necessary values preserved, and review the PlaylistItems update reference before relying on a minimal payload. This is particularly important when changing snippet.position while also supplying playlist and video resource details.
Treat an API response as part of the job's result. If authentication fails, the item is missing, the playlist rejects the operation, or the request returns an error, the script should report the problem and exit unsuccessfully. A zero exit status should mean the intended change was confirmed, not merely that the script started. Send useful diagnostic messages to standard error or the journal, but never print credentials.
Build in a preview or dry-run mode if your script will make consequential edits. A preview can show the playlist, target item, operation and intended position without sending the write request. For a first live test, prefer a private or otherwise low-risk playlist you control, and choose an edit that is easy to inspect and undo. Keep a record of what the script intended to change so you can distinguish a successful API call from a later playback or display delay.
Create a systemd service unit
A service unit defines how the script runs. For a user-level service, place the unit in the appropriate user configuration directory; for a system service, use the system's service unit path and specify the intended account. Exact paths and security settings differ between distributions, so consult the local systemd documentation before installing a unit. The core is to set a clear description, the script's executable path, and a predictable execution environment.
A simple service might look like this, with paths and user details adapted to your host:
[Unit]
Description=Apply a scheduled YouTube playlist change
[Service]
Type=oneshot
User=channelops
WorkingDirectory=/home/channelops/youtube-playlist
ExecStart=/usr/local/bin/python3 /home/channelops/youtube-playlist/change_playlist.py
This example is a pattern, not a complete OAuth implementation. If your script needs environment settings, define them deliberately in an appropriately protected configuration file or through the mechanism you have selected. Use absolute paths for the interpreter and script, and ensure the service user can read the script, configuration and authorised credentials. A missing working directory or a shorter PATH than your login shell has can cause a job that works interactively to fail under systemd.
Run the script manually as the service user first, then ask systemd to start the service directly. Inspect the unit's status and journal output before enabling a timer. If the script fails, resolve its exit code, permissions, OAuth or API issue at this stage. There is no benefit in adding a schedule to an operation that is not yet reliable when invoked by hand.
Schedule it with an OnCalendar timer
A calendar timer expresses a wall-clock schedule. For example, a timer intended to run a playlist edit each day at a chosen local time can use an OnCalendar= expression, then activate the service. A basic unit could be:
[Unit]
Description=Schedule the YouTube playlist change
[Timer]
OnCalendar=*-*-* 06:30:00
Persistent=true
Unit=youtube-playlist-change.service
[Install]
WantedBy=timers.target
The time in the example is illustrative; choose a time zone and local schedule that suit the machine and channel. Timer calendar interpretation can depend on the host's time-zone configuration. Check the installed version's systemd.timer(5) manual and validate the expression with the systemd calendar verification tool available on that machine. systemd documentation is updated over time, and not every directive shown in an upstream manual exists in every installed release.
The timer can name its activated unit explicitly with Unit=. If omitted, systemd normally derives a same-name service by removing the timer suffix, so youtube-playlist-change.timer activates youtube-playlist-change.service. Using an explicit setting can make the relationship clearer when names differ. Enable and start the timer rather than treating the service itself as the schedule; the service can still be started manually for diagnosis.
Use a calendar trigger when the requirement is tied to a time on the clock, such as changing a playlist before a morning programme. For elapsed intervals, systemd also offers monotonic timer forms; those represent time since an event or activation rather than a particular time of day. Read the local manual before choosing between them. If several similar jobs should not all execute at precisely the same instant, a randomised delay is available, but it changes when the job runs and should not be used when the playlist must change at a precise time.
Handle missed runs and test the workflow
With a calendar timer, Persistent=true records that a scheduled event was missed while the timer was inactive and triggers an activation when the timer becomes active again. That is useful if a home machine is powered down during a daily schedule. It is a catch-up invocation, not a queue of every missed occurrence: design the script around the state you want now, rather than expecting every historical edit to be replayed.
Ask what a late edit should mean. If the task is “ensure this video is in the playlist”, a delayed run can check current membership and add it only if absent. If the task is “remove the item that was scheduled for yesterday”, a catch-up may still be correct, or it may now be stale. For a sequence of different edits, store or derive the desired state from the current date and inspect it before acting. Do not let a missed event blindly repeat an operation whose context has passed.
Test from the inside out. First run the script by hand with a harmless target and inspect the playlist. Next start the service and read its logs. Then validate the calendar expression, enable the timer, and inspect its next elapse time and status. Finally, test the host's expected restart or reboot scenario and verify whether the timer behaves as intended. Keep one known-good manual invocation and its output as a comparison point when diagnosing a scheduled failure.
Check logs after the scheduled event, not just whether the timer is active. A timer can activate successfully while the script exits with an error. Use systemd's status and journal tools for the service and timer, and make the script's failure exit non-zero. If the job is idempotent where practical and reports exactly which item it found or changed, a rerun after diagnosis is safer than guessing whether the first attempt took effect.
Finally, separate the playlist's state from the live channel's state. A playlist edit may affect a viewer's playlist order or future browsing, but it does not reconfigure an encoder or automatically replace a live source. If you are changing a continuous stream's media sequence, examine the player or broadcasting workflow itself; guidance on streaming a video folder with FFmpeg on a Raspberry Pi concerns that distinct path. Likewise, playlist edits do not fix dropped frames or a poor outgoing connection; the 1080p continuous-stream guide addresses broadcast delivery rather than playlist membership.
Before committing, compare the operating options on the pricing page. When the file and channel are ready, start free — 24-hour trial, no card.
FAQ
Does a systemd timer change what is playing on my YouTube live stream?
No. The timer runs a service, and a script can use the YouTube Data API to edit playlist entries. That is separate from the encoder or playback system sending content to a live broadcast, so a playlist edit does not automatically switch a live feed.
Can I use an API key to add or reorder playlist items?
The documented write methods require OAuth authorisation; an API key alone is not the documented authorisation for playlist writes. Authorise the account with access to the target playlist and make sure the scheduled service can access the relevant credentials.
What happens if the Linux machine is off at the scheduled time?
For a calendar timer, Persistent=true can cause a catch-up activation when the timer is active again after a missed event. Decide whether that late operation remains useful, and make the script check the current playlist state before making a potentially duplicate or stale change.
Is the video ID the identifier I need to delete a playlist entry?
No. Deletion acts on the playlist-item ID, which identifies the entry in the playlist; the video ID identifies the video itself. If a video occurs more than once or in multiple playlists, confirm the exact playlist item before deleting it.