jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

add ical + m3u

Browse source
This commit is contained in:
JMARyA 2024-03-07 00:08:48 +01:00
parent dc3496459a
commit 6874ff8b96
Signed by: jmarya
GPG key ID: 901B2ADDF27C2263
2 changed files with 252 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

166
technology/files/iCalendar.md Normal file
View file

@ -0,0 +1,166 @@
---
obj: format
wiki: https://en.wikipedia.org/wiki/ICalendar
rfc: https://datatracker.ietf.org/doc/html/rfc5545
mime: text/calendar
extension: ics
aliases: ["ics"]
---
# iCalendar
The Internet Calendaring and Scheduling Core Object Specification (iCalendar) is a media type which allows users to store and exchange calendaring and scheduling information such as events, to-dos, journal entries, and free/busy information, and together with its associated standards has been a cornerstone of the standardization and interoperability of digital calendars across different vendors. Files formatted according to the specification usually have an extension of `.ics`. With supporting software, such as an email reader or calendar application, recipients of an iCalendar data file can respond to the sender easily or counter-propose another meeting date/time. The file format is specified in a proposed Internet standard (RFC 5545) for calendar data exchange. The standard and file type are sometimes referred to as "iCal", which was the name of the Apple Inc. calendar program until 2012 (see iCal), which provides one of the implementations of the standard.
## Format
iCalendar data have the [MIME](MIME.md) content type `text/calendar`. The filename extension of `ics` is to be used for files containing calendaring and scheduling information, `ifb` for files with free or busy time information consistent with this [MIME](MIME.md) content type. There are also variations of this format in [JSON](JSON.md) (jCal) or [XML](XML.md) (xCal).
By default, iCalendar uses the [UTF-8](Unicode.md) character set; a different character set can be specified using the "charset" [MIME](MIME.md) parameter (if the transport method used supports MIME, such as [Email](../internet/eMail.md) or [HTTP](../internet/HTTP.md)). Each line is terminated by `CR+LF` (in hexadecimal: `0D0A`). Lines should be limited to 75 octets (not characters) long. Where a data item is too long to fit on a single line it can be continued on following lines by starting the continuation lines with a space character (in hex: `20`) or a tab character (in hex: `09`). Actual line feeds in data items are encoded as a backslash followed by the letter n or N (the bytes `5C 6E` or `5C 4E` in [UTF-8](Unicode.md)).
The iCalendar format is designed to transmit calendar-based data, such as events, and intentionally does not describe what to do with that data. Thus, other programming may be needed to negotiate what to do with this data. A companion standard, "iCalendar Transport-Independent Interoperability" (iTIP) (RFC 2446), defines a protocol for exchanging iCalendar objects for collaborative calendaring and scheduling between "Calendar Users" (CUs) facilitated by an "Organizer" initiating the exchange of data. This standard defines methods such as `PUBLISH`, `REQUEST`, `REPLY`, `ADD`, `CANCEL`, `REFRESH`, `COUNTER` (to negotiate a change in the entry), and `DECLINE-COUNTER` (to decline the counter-proposal). Another companion standard, "iCalendar Message-based Interoperability Protocol (iMIP)" (RFC 2447), defines a standard method for implementing iTIP on standard Internet [email](../internet/eMail.md)-based transports. The "Guide to Internet Calendaring" (RFC 3283) explains how iCalendar interacts with other calendar computer language (current and future).
The top-level element in iCalendar is the Calendaring and Scheduling Core Object, a collection of calendar and scheduling information. Typically, this information will consist of a single iCalendar object. However, multiple iCalendar objects can be grouped together. The first line must be `BEGIN:VCALENDAR`, and the last line must be `END:VCALENDAR`; the contents between these lines is called the "icalbody". The body must include the `PRODID` and `VERSION` calendar properties. In addition, it must include at least one calendar component.
`VERSION:1.0` is used to specify that data is in the old vCalendar format. `VERSION` is 2.0 for the current iCalendar format as of 2016.
The body of the iCalendar object (the icalbody) contains single-line Calendar Properties that apply to the entire calendar, as well as one or more blocks of multiple lines that each define a Calendar Component such as an event, journal entry, alarm, or one of several other types. Here is a simple example of an iCalendar object with a single calendar containing a single Calendar Component, a "Bastille Day Party" event starting at 5pm on July 14, 1997, and ending at 4am the following morning:
```ics
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
UID:uid1@example.com
DTSTAMP:19970714T170000Z
ORGANIZER;CN=John Doe:MAILTO:john.doe@example.com
DTSTART:19970714T170000Z
DTEND:19970715T040000Z
SUMMARY:Bastille Day Party
GEO:48.85299;2.36885
END:VEVENT
END:VCALENDAR
```
The UID field distributes updates when a scheduled event changes. When the event is first generated a globally unique identifier is created. If a later event is distributed with the same UID, it replaces the original one. An example UID might be `Y2007S2C131M5@example.edu`, for the 5th meeting of class 131 in semester 2 at a hypothetical college. Email-style UIDs are now considered bad practice, with a UUID recommended instead.
The most common representation of date and time is a tz timestamp such as `20010911T124640Z` with the format `<year (4 digits)><month (2)><day (2)>T<hour (2)><minute (2)><second (2)>Z` for a total fixed length of 16 characters. Z indicates the use of UTC (referring to its Zulu time zone). When used in `DTSTART` and `DTEND` properties, start times are inclusive while end times are not. This allows an event's end time to be the same as a consecutive event's start without those events overlapping and potentially creating (false) scheduling conflicts.
Components include:
- `VEVENT` describes an event, which has a scheduled amount of time on a calendar. Normally, when a user accepts the calendar event, this will cause that time to be considered busy, though an event can be set to be `TRANSPARENT` to change this interpretation. A `VEVENT` may include a `VALARM` which allows an alarm. Such events have a `DTSTART` which sets a starting time, and a `DTEND` which sets an ending time. If the calendar event is recurring, `DTSTART` sets up the start of the first event.
- `VTODO` explains a to-do item, i.e., an action-item or assignment. Not all calendar applications recognize `VTODO` items. In particular, Outlook does not export Tasks as `VTODO` items, and ignores `VTODO` items in imported calendars.
- `VJOURNAL` is a journal entry. They attach descriptive text to a particular calendar date, may be used to record a daily record of activities or accomplishments, or describe progress with a related to-do entry. A `VJOURNAL` calendar component does not take up time on a calendar, so it has no effect on free or busy time (just like `TRANSPARENT` entries). In practice, few programs support `VJOURNAL` entries.
- `VFREEBUSY` is a request for free/busy time, is a response to a request, or is a published set of busy time. Other component types include `VAVAILABILITY`, `VTIMEZONE` (time zones) and `VALARM` (alarms). Some components can include other components (`VALARM` is often included in other components). Some components are often defined to support other components defined after them (`VTIMEZONE` is often used this way).
iCalendar is meant to "provide the definition of a common format for openly exchanging calendaring and scheduling information across the Internet". While the features most often used by users are widely supported by iCalendar, some more advanced capabilities have problems. For example, most vendors do not support Journals (`VJOURNAL`). `VTODOs` have had conversion problems as well.
iCalendar's calendar is also not compatible with some non-Gregorian calendars such as the lunar calendars used in Israel and Saudi Arabia. Although there exist one-to-one mappings between Gregorian and many other calendar scales, the lack of defined `CALSCALE` values for those calendars and limitations in various date fields can make native support impossible. For example the Hebrew calendar year may contain either 12 or 13 months, and the Japanese Emperor-based calendar scale contains many eras.
## List of components, properties and parameters
| Name | Kind | RFC section (RFC 5545) |
| -------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `VCALENDAR` | Component | 3.4. iCalendar Object |
| `VEVENT` | Component | 3.6.1. Event Component |
| `VTODO` | Component | 3.6.2. To-Do Component |
| `VJOURNAL` | Component | 3.6.3. Journal Component |
| `VFREEBUSY` | Component | 3.6.4. Free/Busy Component |
| `VTIMEZONE` | Component | 3.6.5. Time Zone Component |
| `STANDARD` | Component | 3.6.5. Time Zone Component |
| `DAYLIGHT` | Component | 3.6.5. Time Zone Component |
| `VALARM` | Component | 3.6.6. Alarm Component |
| `VAVAILABILITY` | Component | RFC 7953 section 3.1. VAVAILABILITY Component |
| `AVAILABLE` | Component | RFC 7953 section 3.1. VAVAILABILITY Component |
| `PARTICIPANT` | Component | RFC 9073 section 7.1. Participant |
| `VLOCATION` | Component | RFC 9073 section 7.2. Location |
| `VRESOURCE` | Component | RFC 9073 section 7.3. Resource |
| `CALSCALE` | Property | 3.7.1. Calendar Scale |
| `METHOD` | Property | 3.7.2. Method |
| `PRODID` | Property | 3.7.3. Product Identifier |
| `VERSION` | Property | 3.7.4. Version |
| `ATTACH` | Property | 3.8.1.1. Attachment |
| `CATEGORIES` | Property | 3.8.1.2. Categories, RFC 7986 section 5.6. CATEGORIES Property |
| `CLASS` | Property | 3.8.1.3. Classification |
| `COMMENT` | Property | 3.8.1.4. Comment |
| `DESCRIPTION` | Property | 3.8.1.5. Description, RFC 7986 section 5.2. DESCRIPTION Property |
| `GEO` | Property | 3.8.1.6. Geographic Position |
| `LOCATION` | Property | 3.8.1.7. Location |
| `PERCENT-COMPLETE` | Property | 3.8.1.8. Percent Complete |
| `PRIORITY` | Property | 3.8.1.9. Priority |
| `RESOURCES` | Property | 3.8.1.10. Resources |
| `STATUS` | Property | 3.8.1.11. Status |
| `SUMMARY` | Property | 3.8.1.12. Summary |
| `COMPLETED` | Property | 3.8.2.1. Date-Time Completed |
| `DTEND` | Property | 3.8.2.2. Date-Time End |
| `DUE` | Property | 3.8.2.3. Date-Time Due |
| `DTSTART` | Property | 3.8.2.4. Date-Time Start |
| `DURATION` | Property | 3.8.2.5. Duration |
| `FREEBUSY` | Property | 3.8.2.6. Free/Busy Time |
| `TRANSP` | Property | 3.8.2.7. Time Transparency |
| `TZID` | Property | 3.8.3.1. Time Zone Identifier |
| `TZNAME` | Property | 3.8.3.2. Time Zone Name |
| `TZOFFSETFROM` | Property | 3.8.3.3. Time Zone Offset From |
| `TZOFFSETTO` | Property | 3.8.3.4. Time Zone Offset To |
| `TZURL` | Property | 3.8.3.5. Time Zone URL |
| `ATTENDEE` | Property | 3.8.4.1. Attendee |
| `CONTACT` | Property | 3.8.4.2. Contact |
| `ORGANIZER` | Property | 3.8.4.3. Organizer |
| `RECURRENCE-ID` | Property | 3.8.4.4. Recurrence ID |
| `RELATED-TO` | Property | 3.8.4.5. Related To, RFC 9253 section 9.1. RELATED-TO |
| `URL` | Property | 3.8.4.6. Uniform Resource Locator, RFC 7986 section 5.5. URL Property |
| `UID` | Property | 3.8.4.7. Unique Identifier, RFC 7986 section 5.3. UID Property |
| `EXDATE` | Property | 3.8.5.1. Exception Date-Times |
| `RDATE` | Property | 3.8.5.2. Recurrence Date-Times |
| `RRULE` | Property | 3.8.5.3. Recurrence Rule |
| `ACTION` | Property | 3.8.6.1. Action |
| `REPEAT` | Property | 3.8.6.2. Repeat Count |
| `TRIGGER` | Property | 3.8.6.3. Trigger |
| `CREATED` | Property | 3.8.7.1. Date-Time Created |
| `DTSTAMP` | Property | 3.8.7.2. Date-Time Stamp |
| `LAST-MODIFIED` | Property | 3.8.7.3. Last Modified, RFC 7986 section 5.4. LAST-MODIFIED Property |
| `SEQUENCE` | Property | 3.8.7.4. Sequence Number |
| `REQUEST-STATUS` | Property | 3.8.8.3. Request Status |
| `BUSYTYPE` | Property | RFC 7953 section 3.2. Busy Time Type |
| `NAME` | Property | RFC 7986 section 5.1. NAME Property |
| `REFRESH-INTERVAL` | Property | RFC 7986 section 5.7. REFRESH-INTERVAL Property |
| `SOURCE` | Property | RFC 7986 section 5.8. SOURCE Property |
| `COLOR` | Property | RFC 7986 section 5.9. COLOR Property |
| `IMAGE` | Property | RFC 7986 section 5.10. IMAGE Property |
| `CONFERENCE` | Property | RFC 7986 section 5.11. CONFERENCE Property |
| `CALENDAR-ADDRESS` | Property | RFC 9073 section 6.4. Calendar Address |
| `LOCATION-TYPE` | Property | RFC 9073 section 6.1. Location Type |
| `PARTICIPANT-TYPE` | Property | RFC 9073 section 6.2. Participant Type |
| `RESOURCE-TYPE` | Property | RFC 9073 section 6.3. Resource Type |
| `STRUCTURED-DATA` | Property | RFC 9073 section 6.6. Structured-Data |
| `STYLED-DESCRIPTION` | Property | RFC 9073 section 6.5. Styled-Description |
| `ACKNOWLEDGED` | Property | RFC 9074 section 6.1. Acknowledged Property |
| `PROXIMITY` | Property | RFC 9074 section 8.1. Proximity Property |
| `CONCEPT` | Property | RFC 9253 section 8.1. Concept |
| `LINK` | Property | RFC 9253 section 8.2. Link |
| `REFID` | Property | RFC 9253 section 8.3. Refid |
| `ALTREP` | Parameter | 3.2.1. Alternate Text Representation |
| `CN` | Parameter | 3.2.2. Common Name |
| `CUTYPE` | Parameter | 3.2.3. Calendar User Type |
| `DELEGATED-FROM` | Parameter | 3.2.4. Delegators |
| `DELEGATED-TO` | Parameter | 3.2.5. Delegatees |
| `DIR` | Parameter | 3.2.6. Directory Entry Reference |
| `ENCODING` | Parameter | 3.2.7. Inline Encoding |
| `FMTTYPE` | Parameter | 3.2.8. Format Type |
| `FBTYPE` | Parameter | 3.2.9. Free/Busy Time Type |
| `LANGUAGE` | Parameter | 3.2.10. Language |
| `MEMBER` | Parameter | 3.2.11. Group or List Membership |
| `PARTSTAT` | Parameter | 3.2.12. Participation Status |
| `RANGE` | Parameter | 3.2.13. Recurrence Identifier Range |
| `RELATED` | Parameter | 3.2.14. Alarm Trigger Relationship |
| `RELTYPE` | Parameter | 3.2.15. Relationship Type, RFC 9074 7.1. Relationship Type Property Parameter, RFC 9253 4 and 5 |
| `ROLE` | Parameter | 3.2.16. Participation Role |
| `RSVP` | Parameter | 3.2.17. RSVP Expectation |
| `SENT-BY` | Parameter | 3.2.18. Sent By |
| `TZID` | Parameter | 3.2.19. Time Zone Identifier |
| `VALUE` | Parameter | 3.2.20. Value Data Types |
| `DISPLAY` | Parameter | RFC 7986 section 6.1. DISPLAY Property Parameter |
| `EMAIL` | Parameter | RFC 7986 section 6.2. EMAIL Property Parameter |
| `FEATURE` | Parameter | RFC 7986 section 6.3. FEATURE Property Parameter |
| `LABEL` | Parameter | RFC 7986 section 6.4. LABEL Property Parameter |
| `ORDER` | Parameter | RFC 9073 section 5.1. Order |
| `SCHEMA` | Parameter | RFC 9073 section 5.2. Schema |
| `DERIVED` | Parameter | RFC 9073 section 5.3. Derived |
| `GAP` | Parameter | RFC 9253 section 6.2. Gap |
| `LINKREL` | Parameter | RFC 9253 section 6.1. Link Relation |

86
technology/files/media/m3u.md Normal file
View file

@ -0,0 +1,86 @@
---
obj: format
wiki: https://en.wikipedia.org/wiki/M3U
extension: ["m3u", "m3u8"]
mime: audio/x-mpegurl
---
# m3u Playlist
M3U is a computer file format for a multimedia playlist. One common use of the M3U file format is creating a single-entry playlist file pointing to a stream on the Internet. The created file provides easy access to that stream and is often used in downloads from a website, for emailing, and for listening to Internet radio.
Although originally designed for audio files, such as MP3, it is commonly used to point media players to audio and video sources, including online sources. M3U was originally developed by Fraunhofer for use with their Winplay3 software, but numerous media players and software applications now support the format.
## Format
There is no formal specification for the M3U format; it is a de facto standard.
An M3U file is a plain text file that specifies the locations of one or more media files. The file is saved with the "m3u" filename extension if the text is encoded in the local system's default non-[Unicode](../Unicode.md) encoding, or with the "m3u8" extension if the text is [UTF-8](../Unicode.md) encoded.
Each entry carries one specification. The specification can be any one of the following:
- an absolute local pathname; e.g., `/My Music/Heavysets.mp3`
- a local pathname relative to the M3U file location; e.g. `Heavysets.mp3`
- a URL
Each entry ends with a line break which separates it from the following one.
### Extended
The M3U file can also include comments, prefaced by the `#` character. In extended M3U, `#` also introduces extended M3U directives which are terminated by a colon `:` if they support parameters.
M3U extensions:
| Directive | Description | Example |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `#EXTM3U` | file header, must be the first line of the file | `#EXTM3U` |
| `#EXTINF:` | track information: runtime in seconds and display title of the following resource<br>additional properties as key-value pairs | `#EXTINF:123,Artist Name – Track Title`<br>`#EXTINF:123 logo="cover.jpg",Track Title` |
| `#PLAYLIST:` | playlist display title | `#PLAYLIST:Music TV` |
| `#EXTGRP:` | begin named grouping | `#EXTGRP:Foreign Channels` |
| `#EXTALB:` | album information, title in particular | `#EXTALB:Album Title (2009)` |
| `#EXTART:` | album artist | `#EXTART:Various` |
| `#EXTGENRE:` | album genre | `#EXTGENRE:Jazz Fusion` |
| `#EXTM3A` | playlist for tracks or chapters of an album in a single file | `#EXTM3A` |
| `#EXTBYT:` | file size in bytes | `#EXTBYT:34124` |
| `#EXTBIN:` | binary data follows, usually concatenated MP3s | `#EXTBIN:` |
| `#EXTENC:` | text encoding, must be the second line of the file | `#EXTENC:UTF-8` |
| `#EXTIMG:` | cover, logo or other image | `#EXTIMG:cover.jpg` |
Apple used the extended M3U format as a base for their HTTP Live Streaming (HLS) which was documented in an Independent Submission Stream RFC in 2017 as RFC 8216. Therein, a master playlist references segment playlists which usually contain URLs for short parts of the media stream. Some tags only apply to the former type and some only to the latter type of playlist, but they all begin with `#EXT-X-`.
HLS M3U extensions:
| Directive | Example | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `#EXT-X-START:` | `TIME-OFFSET=0` | |
| `#EXT-X-INDEPENDENT-SEGMENTS` | Toggle without parameters | |
| `#EXT-X-PLAYLIST-TYPE:` | `VOD` or `EVENT` | |
| `#EXT-X-TARGETDURATION:` | `10` | The maximum Media Segment duration in seconds |
| `#EXT-X-VERSION:` | `4` | |
| `#EXT-X-MEDIA-SEQUENCE:` | `0` | The Media Sequence Number of the first Media Segment appearing in the playlist file |
| `#EXT-X-MEDIA:` | `NAME="English", TYPE=AUDIO, GROUP-ID="audio-stereo-64", LANGUAGE="en", DEFAULT=YES, AUTOSELECT=YES, URI="english.m3u8"` | |
| `#EXT-X-STREAM-INF:` | `BANDWIDTH=1123000, CODECS="avc1.64001f,mp4a.40.2` | Parameters have either one combined value or one per stream, separated by commas |
| `#EXT-X-BYTERANGE:` | `1024@256000` | |
| `#EXT-X-DISCONTINUITY` | toggle without parameters | The segment represents the start of a new period |
| `#EXT-X-DISCONTINUITY-SEQUENCE:` | `2` | Indicates start of numbering of periods |
| `#EXT-X-GAP` | toggle without parameters | The segment represents a "spacer" before a new period |
| `#EXT-X-KEY:` | `METHOD=NONE` | Indicates encryption method used and decryption key |
| `#EXT-X-MAP:` | `URI=MediaInitializationSection` | |
| `#EXT-X-PROGRAM-DATE-TIME:` | `2010-02-19T14:54:23.031+08:00` | ISO 8601 format |
| `#EXT-X-DATERANGE:` | `ID=foo` | |
| `#EXT-X-I-FRAMES-ONLY` | i-frame Toggle without parameters | |
| `#EXT-X-SESSION-DATA:` | `DATA-ID=com.example.movie.title` | |
| `#EXT-X-SESSION-KEY:` | | |
| `#EXT-X-ENDLIST` | End-of-list signal without parameters | |
### M3U8
The [Unicode](../Unicode.md) version of M3U is M3U8, which uses [UTF-8](../Unicode.md)-encoded characters. M3U8 files are the basis for the HTTP Live Streaming (HLS) format originally developed by Apple to stream video and radio to iOS devices, and which is now a popular format for adaptive streaming in general.
The 2015 proposal for the HLS playlist format uses [UTF-8](../Unicode.md) exclusively and does not distinguish between the "m3u" and "m3u8" file name extensions.
## Examples
```m3u
#EXTM3U
#EXTINF:123, Sample artist - Sample title
C:\Documents and Settings\I\My Music\Sample.mp3
#EXTINF:321,Example Artist - Example title
C:\Documents and Settings\I\My Music\Greatest Hits\Example.ogg
```