= Deck file format reference
:toc: preamble
:toc-title:

A deck file is composed of <<config,config lines>> and <<notes,notes>>:

[,yaml]
----
# These are config lines. They set configuration for the deck and for the
# generated flash cards.
title: Basic ASL phrases
more: md:From [Lifeprint](https://www.lifeprint.com/)
audio: strip

# These are notes. They represent flashcards.
https://www.youtube.com/watch?v=FHPszRvL9pg What is your name?
https://www.youtube.com/watch?v=zW8cpOVeKZ4 Are you deaf?
https://www.youtube.com/watch?v=xqKENRGkOUQ Are you a student?
----

[#notes]
== Notes

Notes represent collections of one or two flashcards. For example, the following
line defines a note that is composed of two cards:

 https://www.youtube.com/watch?v=UyfRF3TeLPs YOUR NAME?

The cards are (question → answer):

* Video → “`YOUR NAME?`”
* “`YOUR NAME?`” → Video

If the text component is left off, Yanki will use the title of the video if it’s
available.

If the line gets too long, you can continue on the following line by indenting
it, for example:

 https://www.youtube.com/watch?v=UDM9KJJtRbE
   YOU DIVORCE-[non-initialized] YOU?

[#direction]
=== Direction (`+<-+`, `+<->+`, `+->+`)

You may customize which cards are generated using a direction sign. For example,
the following will only generate one card, which will first display the video,
then the text:

 https://www.youtube.com/watch?v=_V31e361KV8 -> WHO? (legacy version)

You may also use `+<-+` for a single card going from text to video, or you may
explicitly set a note to generate both cards with `+<->+` (this is the default
behavior).

[#clip]
=== Clip (`@time-time`)

Clip the start and/or end of the video. `time` can be a frame (`#F`, e.g.
`32F`), a timestamp (`MM:SS.sss` or just `SS.sss`, e.g. `1:02`), or can be left
blank to mean the natural start or end.

For example, you could specify `@1:00-` to trim 1 minute off the beginning of
the video, or `@0.5-70f` to trim the first half second off the video and then
end the video at the 70th frame (counting from the original video start).

Normally you can’t have two cards with the same video URL in a deck (see
<<note_id,`note_id`>> below), but if you specify a clip you can use the same
video multiple times. This is useful if you need to split a video into multiple
cards.

For example, https://www.youtube.com/watch?v=M4AFC4eEjlQ[this video] has all
of the numbers in ASL from 1 to 100. You could make flashcards for 11, 12, and
13 like so:

 https://www.youtube.com/watch?v=M4AFC4eEjlQ @390F-430F 11
 https://www.youtube.com/watch?v=M4AFC4eEjlQ @450F-482F 12
 https://www.youtube.com/watch?v=M4AFC4eEjlQ @505F-545F 13

If you only want to clip the blank or still frames from the beginning or end of
videos, see <<trim,`trim:`>> below.

[#snapshot]
=== Snapshot (`@time`)

You can snapshot a video by specifying a single frame (`@#F`) or a timestamp
(`@MM:SS.sss` or just `@SS.sss`). For example, this generates cards with a still
image from frame 320:

 https://www.youtube.com/watch?v=M4AFC4eEjlQ @320F 9

[#config]
== Config lines

Config lines set configuration for future notes, unless they’re _inside_ a
note, in which case they set the configuration for that note and nothing else.

[,yaml]
----
https://www.youtube.com/watch?v=FHPszRvL9pg note 1

overlay_text: deck

https://www.youtube.com/watch?v=UyfRF3TeLPs note 2
  overlay_text: note

https://www.youtube.com/watch?v=zW8cpOVeKZ4 note 3
----

The above example produces 3 notes (and 6 cards):

|===
| Note text | Overlay text

| note 1
|

| note 2
| note

| note 3
| deck

|===


[#title]
=== `title:` -- Deck title

`title` sets the title of the deck. You _must_ set this somewhere in your deck
file. I recommend putting it right at the top for clarity.

[#group]
=== `group:` -- Group notes together for easy configuration

This allows you to set configuration on a group of notes without affecting
anything else in the deck. Example:

[,yaml]
----
group:
  more: +md:[FIRST](https://www.lifeprint.com/asl101/pages-signs/f/first.htm)
  https://www.youtube.com/watch?v=tZ04_s30aXY FIRST / primary

  tags: +extra
  https://www.youtube.com/watch?v=x9xgoFqsBkE FIRST-PLACE
----

Each config set on the group only applies to the notes after it, so the `more`
line applies to both, and the `tags` line only applies to the last note.

Neither applies to any notes outside the group.

You may nest groups.

[#more]
=== `more:` -- Add more information to answer card

This configuration adds more information to the answer side of each card
generated by a note. For example:

[,yaml]
----
file://video.mp4 text
  more: added context
----

The above generates two cards:

* _video.mp4_ → “`text`” “`added context`”
* “`text`” → _video.mp4_ “`added context`”

You may set content in four formats:

* *No prefix*, e.g. `more: some text`. This converts URLs into links and
  HTML-escapes the content. Appropriate for plain text.
* `html:`, e.g. `more: html:<b>text</b>`. This passes the text through (minus
  the “`html:`” prefix) and renders it as HTML in Anki.
* `rst:` This renders the following text as
  https://docutils.sourceforge.io/rst.html[reStructuredText].
* `md:` This renders the following text as
  https://commonmark.org[CommonMark Markdown].

You may also use a plus before any prefix to append the rendered text to the
whatever has already been set. For example:

[,yaml]
----
more: html:<b>First</b>
file://video.mp4 text
  more: +md: _second_
----

The above generates a note with the `more` text set to “`*First* _second_`”.

[#crop]
=== `crop:` -- Crop visual media

Crop the media to a certain size in _width_:__height__ format. This can be an
absolute pixel value, e.g. `300:500`, or it can be an expression based on `in_h`
and/or `in_w`. For example, `crop: in_h:in_h` will crop the video to a square of
the size of the input height.

See `ffmpeg`’s https://ffmpeg.org/ffmpeg-filters.html#crop[`crop` filter] for
more possibilities.

Note that Yanki always scales images and videos to be 500px tall while
maintaining their aspect ratio. The scaling happens after cropping.

[#trim]
=== `trim:` -- Cut the start and/or end off the video

This works similarly to <<clip,clip (`@time-time`)>>, explained above. It takes
the same parameters.

The difference is that it doesn’t affect the <<note_id,`note_id`>>. This has two
advantages:

. You can come back and adjust `trim` later and Anki will correctly update the
  existing cards rather than creating new ones.
. It can help avoid duplicate videos. If you use slightly different clips for
  the same video URL, Yanki will treat them as distinct cards. If you used
  `trim:` instead, it will flag them as duplicates.

[#slow]
=== `slow:` -- Slow down or speed up part of the media

Sometimes a video, or just a part of a video, is too slow or too fast. The
`slow` configuration allows you to fix that. The following slows down the video
to half speed from 0.5 seconds to 1.0 seconds:

[,yaml]
----
slow: 0.5-1 *2
----

You can leave off one or both of the times to slow from the start or to the end
of the video. For example, the following speeds up the end of the video
(starting at the 60th frame) by twice:

[,yaml]
----
slow: 60F- *0.5
----

`slow` can only be applied to one part of a video (or audio track).

[#tags]
=== `tags:` -- Set tags for notes

Tags are separated by spaces. You can prefix tags with `+` or `-` to add or
remove them from the existing tag set. For example:

[,yaml]
----
title: Example
tags: phrases wh-question

https://www.youtube.com/watch?v=FHPszRvL9pg What is your name?

group:
  tags: -wh-question +yes-no

  https://www.youtube.com/watch?v=zW8cpOVeKZ4 Are you deaf?
  https://www.youtube.com/watch?v=xqKENRGkOUQ Are you a student?

# This note has its tags overridden:
https://www.youtube.com/watch?v=sMRpqyQK72c
  HEARING-[a culturally hearing person]
  tags: vocabulary
----

The above file results in notes with the following tags:

|===
| Note text | Tags

| What is your name?
| phrases, wh-question

| Are you deaf?
| phrases, yes-no

| Are you a student?
| phrases, yes-no

| HEARING-[a culturally hearing person]
| vocabulary
|===

[#overlay_text]
=== `overlay_text:` -- Set overlay text to appear on the video

Overlay text can be added to videos or images. It’s always white text on a
semi-transparent black box in the upper left corner. It does not support any
kind of styling.

[#note_id]
=== `note_id:` -- Note GUIDs

Anki uses the GUID (Globally Unique ID) field to identify notes for update.
By default, Yanki generates GUIDs based on the deck ID (generated from the deck
title), the video URL, and the clip of the video (e.g. `@0:01-0:02`).

You can customize how the GUID is generated with the `note_id` configuration:

[,yaml]
----
# Default:
note_id: {deck_id} {url} {clip}

# Use the text that corresponds to the video:
note_id: {deck_id} {text}
----

Leaving out `+{deck_id}+` can be useful if you might need to move notes between
decks later on. Unfortunately, Anki’s import will not actually move notes from
one deck to another, but it will update them in the other deck. You can then
move them manually. This is useful if you want to keep your study progress.

If you do leave out `+{deck_id}+`, you should probably include something else to
make sure the GUID is unique outside of your decks. For example:

[,yaml]
----
title: Really Cool Cards::subdeck 1
note_id: Really Cool Cards {url} {clip}
----

[#audio]
=== `audio:` -- Whether to keep or strip audio from a video

* `include` (default) -- keep all audio tracks in place.
* `strip` -- remove all audio tracks.

[#video]
=== `video:` -- Whether to keep or strip video from a video

* `include` (default) -- keep video.
* `strip` -- remove video, presumably leaving just audio.

[#format]
=== `format:` -- File extension to use for generated media

The file extension of the media to generate (default: `mp4`). You may wish to
use something else, e.g. `mp3`, if you are stripping the video and just using
the audio tracks.
