C64 OS is an operating system for the Commodore 64 and 128 computers. You can read all about C64 OS here. Most modern operating systems make transparent use of Cloud Services to augment the user experience and provide many valuable features.
The abundance of WiFi modems and ethernet solutions available to C64/128 users, at very reasonable prices, means there is very little excuse for us all not to have internet access on our favorite 8-Bit computers. One reason not to have internet access, though, is a lack of usefulness.
C64 OS itself aims to change the problem of usefulness, by baking network services into many parts of the OS. And the Cloud Services that C64 OS access is a suite of endpoints specifically designed to make the internet more easily digestible and discoverable by Commodore 8-Bit computers. The services are hosted services.c64os.com. If our usage begins to outstrip its bandwidth and computational resources, it would be very useful if others in the community would donate their bandwidth and computation and mirror the services. We could even have a service, whose sole purpose is list available mirrors which could be selected from either manually or at random, to distribute the load.
Every attempt will be made to keep the services backwards compatible, as new features get added. If a service ever requires a complete rewrite, it will be given a new endpoint. New services will be added as time goes on. And ideas, for new services and additional features, are always welcome.
—Greg Naçu (Contact Me)
http://services.c64os.com/
All services listed below have an endpoint. The endpoint is a resource which is available at the Base URL. Mirrors of C64 OS Services will provide a different Base URL. Information about each service is, therefore, presented independently of the server that is hosting the Services.
If a service lists its endpoint merely as image, then the full URL will be: http://services.c64os.com/image
All parameters are sent as URL encoded GET variables. Some but not all parameters may be combined together in the same request. Each parameter will specify what it can be combined with.
If a service lists parameters: u for input URL, and g for gamma value between 1 and 10, then they would be used in the full URL like this: http://services.c64os.com/image?u=http://some.url.com/someimage.png&g=2
All services that output text, process the text first through a common suite of ASCII text simplifications. These include:
The C64 cannot display characters outside of the ordinary 7-bit ASCII range. But on today's internet text is littered with unicode characters, emoji being among the most popular. UTF-8 is the most common way for files to be encoded today, but many texts also use HTML entities to encode these extended characters.
Unicode to text converts 1,500 emoji and other common unicode characters to its english language text description surrounded by braces. Like this:
🌨 becomes {cloud_with_snow} and 🏀 becomes {basketball}
It makes the text more verbose, but it is the only way to capture the meaning. The only alternative is to lose the symbol entirely, which could impair comprehension of the text.
All other Unmatched UTF-8 characters are converted to HTML entities. And then, finally, a set of around 60 (more will be added as they are identified) entites are converted to some sensible plaintext equivalent. Like this:
© becomes (c) and ¼ becomes 1/4
Entities which are not being replaced by a simplified plaintext representation are left as entities, which are more human readable than would be the case if they were left as multi-byte UTF-8 characters.
image
Takes a source URL to an image file. Downloads the image, scales it, reduces its colors to the C64 palette, and outputs to the specified output format. The default is Koala.
Allows a C64 program, which has the URL to an image file, to request the image file via the image proxy, and directly download a preconverted version of the file ready to be displayed or saved for later.
[A fully qualified URL] (default: http://www.c64os.com/resources/c64c-system.jpg) URL to source image. Supports http and https. IP addresses are not supported for security reasons.
[jpg|gif|png] Input format of source image. The input format is detected automatically by the extension on the file in the source URL. However, if the file is misnamed or is not specified explicitly, this parameter can override that.
[koala|jpg|gif|png] (default: koala) Output image format. Defaults to koala. If the output format is Koala, an addtional header is sent, for content-disposition: attachment, with a filename. This will cause normal browser to download and save the file. Other output formats will be rendered in the browser as any regular image.
[RGB Color Definition] (Optional) PNG files support alpha transparency. When converting the images are automatically matted to a solid background color. If bg is not specified, the background color is first selected from the PNG file's own background specification. If the PNG has no background segment, white is used by default. See the RGB Color Definition file for a list of color names that can be used as the argument.
[1 ... 100] (default: 100) Simple Dithering. Not the same as Floyd Steinberg Dithering. Should not be combined with FS dithering. Maybe used to give finer grain control over the amount of dithering which can be useful for improving the clarity of certain types of images.
[0 ... 20] (default: 7) Luminance
[-255 ... 255] (default: 0) Brightness
[-100 ... 100] (default: 0) Contrast
[1|0] (default: 1) Color Mapping is combined with Floyd Steinberg dithering. If Floyd Steinberg dithering is turned on, Color Mapping must be turned on. Color Mapping may be used without FS dithering.
[1|0] (default: 0) Floyd Steinberg dithering. FS dithering must be combined with Color Mapping, and cannot be combined with Simple Dither, Luminance, Brightness or Contrast.
[0.5 ... 5] (default: 1) Scale Factor. Scales in multiples of 320x200. This is for output to JPG, GIF, and PNG only. Can be useful for seeing a graphic blown up, in a browser.
images
Takes one or more search keywords, and looks up those keywords in an image search engine. Returns a block of paired lines, description and URL to image file.
Allows a C64 program to obtain the URL to an image file, by search keywords, which can be sent back to the image conversion service, to download and view.
[One or more search term] (default: "Commodore 64") Search Terms
[1...20] (default: 4) "ct" stands for count. It is the maximum number of matching results that will be returned.
[0...200] (default: 0) "ct" stands for start. It is the start offset into the matching results, for the first result that will be returned.
[any string 1 or more bytes long] (default: 0x00 (NULL byte)) For C64 output, the strings are NULL terminated, and the result lines have a fixed length of 64 bytes including the NULL terminator. To view the contents in a more friendly way on the web, a custom delimiter can be specified, such as "<br>"
sid
A combination of an HVSC SID search API, and repository from which SID tunes can be directly downloaded.
The service is intended to be used by the C64 itself. Other services exist to help PCs browse the complete HVSC. More technically, this API is to find and download SIDs that have been relocated (using sidreloc) to make them compatible with C64 OS. All SIDs are relocated to start at $2000. If the original was not page aligned, sidreloc doesn't make it page aligned, so it may actually start anywhere within page $20. The original PSID header is still attached, and has to be parsed to determine the exact location where the SID data needs to be put, within page $20, as well as the exact addresses of its init and play routines. All ZeroPage address have been relocated to fall between $b0 and $b3.
Search parameters that can be combined together are ANDed, making the results progressively more narrow. Some limitations on parameter combinations exist and are specified with each parameter.
C stands for "chance." One SID tune will be selected at random. This cannot be used with any other search parameters.
Specify an exact release year. Cannot be combined with u or l.
Specify upper bound for year. eg. u=1990 will find tunes only released in 1990 or earlier. Cannot be combined with y.
Specify lower bound for year. eg. l=1987 will find tunes only released in 1987 or later. Cannot be combined with y.
Case insensitive match on partial name. eg. n=dance finds "Dance Trial", "Air Dance 4 (remixed)", "Rhythm is a dancer", "Nuclear Dance", etc.
Case insensitive match on partial author. eg. a=tim finds "Tim Gibson", "The ultimate", etc.
Case insensitive match on partial released. eg. r=x finds "1989 Exact", "1988 sphinx", etc.
[1 ... 64] Returns matches on kilobyte size. SID files are rounded up to the next nearest kilobyte. Omit this parameter altogether to not filter by kilobyte size.
[1 ... N] (default: 10) Limits the number of matching results. eg. t=15 will limit the search to 15 results.
(default: newline, \n) Allows you to override the column delimiter. The default is a single newline.
(default: two newlines, \n\n) Allows you to override the row delimiter. The default is two newlines.
[1|0] (default: 0) Optionally use an HTML separator. This will change the results separator from \n to <br>. This is useful if you are making requests in a webbrowser, the results are made easier to read, but harder for a C64 to parse. See "Search Results Format" below. If this parameter is used, it overrides anything specified by cd and/or rd.
[0 ... 3] (default: 3)
Selects the filename mode.
0 = Original HVSC filename
1 = Original Unique. HVSC filename modified with an _XX number to make it unique.
2 = C64 Optimized, 16 character filename
3 = C64 Optimized Unique. 16 character unique filename
Every search result consists of a set of 8 fields separated by \n (0x10) newline characters. The fields are listed in the following order:
Sets of search results are separated by a newline character. The final field of a search result is terminated by a newline like all the other fields, therefore two newlines appear side-by-side between results.
[1 ... MAXTUNEID] (default: 100) Selects a specific tune by its Tune ID, the first field from the search results. Make two requests, one request with search parameters to find the Tune ID. And a second request to download the tune by its ID.
Retrieve a tune's details, rather than downloading it. This can only be used together with i. It allows you to browse the catalog manually by ID.
Search Example:
http://services.c64os.com/sid?l=1994&u=1995&t=2&s=4Result:
4 Koleda Mariusz Lotocki (Arog) 1995 Snake/Vulture 0:39 koleda.sid 4 demos 168 Desant Trampek Artur Gronicki (Smaller) 1994 Anti 1:30 desant-tramp.sid 4 demos
Download Example:
http://services.c64os.com/sid?i=168The download example link downloads desant-tramp.sid, according to the search results.
atom
Atom is an XML-based alternative to RSS. Takes a source URL to an Atom Feed and returns
one of two results: A meta description of the feed. Or, a list of article titles and
their accompanying web links. Both in a very simplified text line-based format.
Allows a C64 program, which has the URL to an Atom feed, to request information about
the feed to discover if new articles are available. If new articles are available, it
allows the C64 to retrieve a list of article titles and their links. It obviates the
need for the C64 to deal with XML, and removes all but the most relevant information
for easy digestion with extreme memory limitations.
This service can also be used to discover recent and popular atom feeds, helping C64
users to discover new content on the web.
[A fully qualified Atom Feed URL] (default: https://www.theregister.co.uk/headlines.atom) URL to an Atom Feed. Supports http and https.
[m|e|r|p|f] (default: m)
A stands for "action".
m is to retrieve meta data about the feed.
e is used to return a list of entries for the feed.
r returns a list of Atom feeds most recently accessed via this webservice.
p returns a list of Atom feeds ordered by their popularity with this webservice.
f is for debug purposes, it returns the entire feed encoded in JSON.
[1 ... N] (default: 10) Used with the entries (e), recent (r), and popular (p), actions. Limits the number of results returned. eg. t=15 will limit the number of results to 15.
[1|0] (default: 0) Optionally use an HTML separator. This will change the results separator from \n to <br>. This is useful if you are making requests in a webbrowser, the results are made easier to read, but harder for a C64 to parse. See "Meta data results" and "Entries Format" below.
Each piece of meta data is on its own line, and is preceded by label with a colon and space before the data.
Title: a title
Subtitle: a subtitle
Id: an identifier
Updated: a date/time stamp
Rights: copyright information
Entries: count of entries in the feed
Meta data request example:
http://services.c64os.com/atom?u=https://daringfireball.net/feeds/main&a=m
Every entry consists of a set of 3 fields separated by \n (0x10) newline characters. The fields are listed in the following order:
Sets of entries are separated by a newline character. The final field of an entry is terminated by a newline like all the other fields, therefore two newlines appear side-by-side between entries.
Entries request example:
http://services.c64os.com/atom?u=https://daringfireball.net/feeds/main&a=e
Result:
Neue Haas Grotesk, the Other New ‘Helvetica’ 2019-04-12T23:14:53Z http://www.fontbureau.com/NHG/ Jackassery Never Goes Out of Style 2019-04-13T00:21:23Z https://www.marketwatch.com/story/as-apples-stock-rides-high-7-reasons-investors-should-worry-2019-04-12 CoreAnimation Bug in MacOS 10.14.4 2019-04-12T21:27:35Z https://www.omnigroup.com/blog/
When requesting a list of feeds either by recent access or popularity, each line consists of a URL. Lines are separated by a \n (0x10) newline character.
Recent/Popular request example:
http://services.c64os.com/atom?a=r
Result:
https://www.theregister.co.uk/science/headlines.atom https://daringfireball.net/feeds/main
