en-us/about_ytdlWrapper_jobs.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
TOPIC
    about_ytdlWrapper_jobs
     
     
     
SHORT DESCRIPTION
    Explains how to set-up and use ytdlWrapper jobs.
     
     
     
OVERVIEW
 == A job is a youtube-dl configuration file which is almost-complete. This file
    will not have everything hardcoded, so when it is executed using the
    `Invoke-YoutubeDl` cmdlet, the stored variables will be used to "fill in"
    the file, and give youtube-dl.exe a valid configuration file.
     
 [!]Due to the nature of a job, the configuration file will not be a valid
    youtube-dl configuration file. It will only be valid once the job is filled
    in when running the `Invoke-YoutubeDl` cmdlet.
     
    There is no limit to how many variables a configuration file can have. It
    can even have zero.
     
     
     
SETTING UP A CONFIGURATION FILE
 == To use a youtube-dl configuration file as a job, it may (commonly) have a
    variable defined. The syntax for a variable definition is:
     
        v@{name}{start{scriptblock}end}
         
        'name' is a string which acts as a user-friendly identifier for this
        variable. The string can only contain the characters: a-zA-Z0-9_
     [!]The string cannot contain a space.
      
         'scriptblock' is a valid powershell scriptblock written out in text. The
        scriptblock must always return a value.
     [!]The module cannot check whether a scriptblock always returns a value, so
         this is on the user to ensure is true.
     
 [!]There are input definitions for a template file. These **cannot** be used
    within a configuration file designed for a job.
     
     
 == An example of using a variable to auto number files:
         
     -> --autonumber-start v@{Number}{start{
            return "6"
        }end}
        --write-thumbnail
        --add-metadata
 
        -f 'best'
        -o '~\downloads\%(autonumber)04d - %(title)s.%(ext)s'
        'https:\\youtube.com\some-id'
     
    When `Invoke-YoutubeDl` is ran with this job, the 'Number' variable is set
    a value from the previous run, and after youtube-dl finishes, the value is
    set to 6.
     
     
     
CREATING A NEW JOB
 == Assuming the configuration file has a variable named 'Number'.
     To create a job, run:
     
        PS C:\> New-YoutubeDlItem -Job -Name "archive" -Path "~\archive.conf" `
                 -Number "5"
                 
    -Name
        Specifies the name of the job to be created; must be unique.
     
    -Path
        Specifies the path of the location of the configuration file to use.
     
 [!]DYNAMIC PARAMETERS
     
    For each variable defined within the configuration file, a parameter with
    the same name will be created to set the variables initial value,
    e.g. '-Number'.
         
    OPTIONAL PARAMETERS
     
    -DontMoveConfigurationFile
        Prevents the configuration file from being moved from its original
        location to a new location in the module appdata folder.
     
    -Force
        Forces this cmdlet to create a job that writes over an existing job.
        Even using this parameter, if the filesystem denies access to the
        necessary files, this cmdlet will fail.
     
    -WhatIf
        Shows what would happen if the cmdlet runs. The cmdlet does not run.
         
    -Confirm
        Prompts you for confirmation before running any state-altering actions
        in this cmdlet.
         
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
     
     
INVOKING A JOB
 == To execute a job, run:
     
        PS C:\> Invoke-YoutubeDl -Job -Name "archive"
         
    This command will execute the "job" template.
     
    -Name
        Specifies the name of the job(s) to run.
     [!]This parameter autocompletes to existing job names.
     
    OPTIONAL PARAMETER
     
    -WhatIf
        Shows what would happen if the cmdlet runs. The cmdlet does not run.
         
    -Confirm
        Prompts you for confirmation before running any state-altering actions
        in this cmdlet.
         
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
     
     
RETRIEVING A JOB
 == To retrieve the details of a job, run:
     
        PS C:\> Get-YoutubeDlItem -Job -Name "archive"
     
    This command will retrieve the details of the job named "archive", and
    print the details to the screen. The output of this cmdlet can be piped
    to a number of other cmdlets in this module.
     
    -Name
        Specifies the name of the job(s) to run.
     [!]This parameter autocompletes to existing job names.
      
    OPTIONAL PARAMETER
     
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
     
     
CHANGING THE PROPERTIES OF A JOB
 == To change the path of the location of the configuration file, run:
     
        PS C:\> Set-YoutubeDlItem -Job -Name "archive" `
                 -Path "~\new_template.conf"
     
    This command will change the path of the location of the configuration
    file from an previous old value to a new one for the job named
    "archive".
     
    The path can be changed to point to the new location of the configuration
    file if it has been moved. Or it can be changed to a different file with
    different input definitions.
     
    -Name
        Specifies the name of the template to edit.
     [!]This parameter autocompletes to existing job names.
     
    -Path
        Specifies the new path of the location of the configuration file to use.
         
    OPTIONAL PARAMETER
     
    -WhatIf
        Shows what would happen if the cmdlet runs. The cmdlet does not run.
         
    -Confirm
        Prompts you for confirmation before running any state-altering actions
        in this cmdlet.
         
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
     
== To change the value of a stored variable, run:
     
        PS C:\> Set-YoutubeDlItem -Job -Name "archive" -Variable "Number" `
                 -Value "100"
                  
    This command will change the value of the 'Number' variable to the new
    value of "100", for the job named "archive".
         
    -Name
        Specifies the name of the template to edit.
     [!]This parameter autocompletes to existing job names.
     
    -Variable
        Specifies the name of the variable to change the value of for a job.
     [!]This parameter autocompletes to the defined variable names within the
        job, once a valid '-Name' value is provided.
         
    -Value
        Specifies the new value of the variable being changed.
         
    OPTIONAL PARAMETER
     
    -WhatIf
        Shows what would happen if the cmdlet runs. The cmdlet does not run.
         
    -Confirm
        Prompts you for confirmation before running any state-altering actions
        in this cmdlet.
         
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
     
 == Assuming the configuration file has a new variable named 'Format'.
     To update a job after changing the configuration file, run:
     
        PS C:\> Set-YoutubeDlItem -Job -Name "archive" -Update `
                 -Format "best"
                  
    This command will sync any changes between the configuration file and the
    job named "archive". The configuration file has a new variable named
    'Format', so an initial value is provided through the '-Format' parameter
    (just like when using the `New-YoutubeDlItem` cmdlet).
     
    If there are any variables which have been removed from the configuration
    file, these will be silently removed from the job as well.
         
    -Name
        Specifies the name of the template to edit.
     [!]This parameter autocompletes to existing job names.
     
 [!]DYNAMIC PARAMETERS
     
    For each **new** variable defined within the configuration file, a parameter
    with the same name will be created to set the variables initial value,
    e.g. '-Format'.
     
    OPTIONAL PARAMETER
     
    -WhatIf
        Shows what would happen if the cmdlet runs. The cmdlet does not run.
         
    -Confirm
        Prompts you for confirmation before running any state-altering actions
        in this cmdlet.
         
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
         
     
REMOVING A JOB
 == To delete a job, run:
     
        PS C:\> Remove-YoutubeDlItem -Job -Name "archive"
         
    This command will delete the job named "archive".
     
    -Name
        Specifies the name of the job(s) to run.
     [!]This parameter autocompletes to existing job names.
      
    OPTIONAL PARAMETER
     
    -WhatIf
        Shows what would happen if the cmdlet runs. The cmdlet does not run.
         
    -Confirm
        Prompts you for confirmation before running any state-altering actions
        in this cmdlet.
         
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
     
     
     
EXAMPLE
 == An example of an archiving job to download an ever-growing youtube playlist:
 
    The configuration file:
     
        --playlist-reverse
        --ignore-errors
        --autonumber-start v@{Number}{start{
            $latestFile = (Get-ChildItem -Path "~\tmp" `
                | Sort-Object -Property LastAccessTime -Descending)[0]
             
            $regex = [regex]::Matches($latestFile.Name, "(\d\d\d\d).*")
            $newValue = [int]$regex.Groups[1].Value + 1
     
            return $newValue
        }end}
        --write-thumbnail
        --add-metadata
        --download-archive ~\archive\downloaded_list.txt
 
        -f '(mp4)[fps>30][height>=1080]+(m4a)/(mp4)[height>=1080]+(m4a)/best'
        -o '~\archive\%(autonumber)04d - %(title)s.%(ext)s'
        'https:\\youtube.com\some-id'
         
    Creating the job:
     
        PS C:\> New-YoutubeDlItem -Job -Name "archive" -Path ~\archive.conf `
                 -Number "5"
         
    Running the job:
     
        PS C:\> Invoke-YoutubeDl -Job -Name "archive"
         
    The result:
     
        In ~\archive\ :
            downloaded_list.txt
            0005 - a video.mp4
            0002 - another video.mp4
            0007 - a further video.mp4
             
        The 'Number' counter is now set to 0008, so the next time the job is
        run, the latest videos will continue at 0008 onwards, continuing the
        numbering scheme.
         
    The next time the job is ran, the new videos will continue with the
    numbering sequence:
     
        In ~\archive\ :
            downloaded_list.txt
            0005 - a video.mp4
            0002 - another video.mp4
            0007 - a further video.mp4
         -> 0008 - new video.mp4
         -> 0009 - newer video.mp4
     
     
     
OTHER
 == If a configuration file is changed and now mismatches what the job object
    has stored, run the `Set-YoutubeDlItem` cmdlet with the '-Update' switch
    to fix any discrepancies. Until this cmdlet is run, you will not be able to
    execute this job.
     
     
 == Using these jobs effectively requires the use of youtube-dl flags and
    features. If you dont know these features, see the youtube-dl documentation
    at:
     
    https://github.com/ytdl-org/youtube-dl
     
     
 == When writing the scriptblocks for a variable definition, you may find it
    easier to write the scriptblock in an interactive powershell session
    (which will also allow you to test the script), and then exporting it out
    as a string to paste into the configuration file, using the
    [Scriptblock]::ToString() method.
     
     
     
KEYWORDS
    ytdlWrapper_jobs
    ytdlWrapper
    Youtube
    Video
    Download
    Wrapper