Package: datasette-media
datasette-mediaDatasette plugin for serving media based on a SQL query.Use this when you have a database table containing references to files on disk - or binary content stored in BLOB columns - that you would like to be able to serve to your users.InstallationInstall this plugin in the same environment as Datasette.$ pip install datasette-mediaHEIC image supportModern iPhones save their photos using theHEIC image format. Processing these images requires an additional dependency,pyheif. You can include this dependency by running:$ pip install datasette-media[heif]UsageYou can use this plugin to configure Datasette to serve static media based on SQL queries to an underlying database table.Media will be served from URLs that start with/-/media/. The full URL to each media asset will look like this:/-/media/type-of-media/media-keytype-of-mediawill correspond to a configured SQL query, and might be something likephoto.media-keywill be an identifier that is used as part of the underlying SQL query to find which file should be served.Serving static files from diskThe followingmetadata.jsonconfiguration will cause this plugin to serve files from disk, based on queries to a database table calledapple_photos.{"plugins":{"datasette-media":{"photo":{"sql":"select filepath from apple_photos where uuid=:key"}}}}A request to/-/media/photo/CF972D33-5324-44F2-8DAE-22CB3182CD31will execute the following SQL query:selectfilepathfromapple_photoswhereuuid=:keyThe value from the URL -  in this caseCF972D33-5324-44F2-8DAE-22CB3182CD31- will be passed as the:keyparameter to the query.The query returns afilepathvalue that has been read from the table. The plugin will then read that file from disk and serve it in response to the request.SQL queries default to running against the first connected database. You can specify a different database to execute the query against using"database": "name_of_db". To execute againstphotos.db, use this:{"plugins":{"datasette-media":{"photo":{"sql":"select filepath from apple_photos where uuid=:key","database":"photos"}}}}Seedogsheep-photosfor an example of an application that can benefit from this plugin.Serving binary content from BLOB columnsIf your SQL query returns acontentcolumn, this will be served directly to the user:{"plugins":{"datasette-media":{"photo":{"sql":"select thumbnail as content from photos where uuid=:key","database":"thumbs"}}}}You can also return acontent_typecolumn which will be used as theContent-Typeheader served to the user:{"plugins":{"datasette-media":{"photo":{"sql":"select body as content, 'text/html;charset=utf-8' as content_type from documents where id=:key","database":"documents"}}}}If you do not specify acontent_typethe default ofapplication/octet-streamwill be used.Serving content proxied from a URLTo serve content that is itself fetched from elsewhere, return acontent_urlcolumn. This can be particularly useful when combined with the ability to resize images (described in the next section).{"plugins":{"datasette-media":{"photos":{"sql":"select photo_url as content_url from photos where id=:key","database":"photos","enable_transform":true}}}}Now you can access resized versions of images from that URL like so:/-/media/photos/13?w=200Setting a download file nameThecontent_filenamecolumn can be returned to force browsers to download the content using a specific file name.{"plugins":{"datasette-media":{"hello":{"sql":"select 'Hello ' || :key as content, 'hello.txt' as content_filename"}}}}Visiting/-/media/hello/Grootwill cause your browser to download a file calledhello.txtcontaining the textHello Groot.Resizing or transforming imagesYour SQL query can specify that an image should be resized and/or converted to another format by returning additional columns. All three are optional.resize_width- the width to resize the image toresize_width- the height to resize the image tooutput_format- the output format to use (e.g.jpegorpng) - any output formatsupported by Pillowis allowed here.If you specify one but not the other ofresize_widthorresize_heightthe unspecified one will be calculated automatically to maintain the aspect ratio of the image.Here's an example configuration that will resize all images to be JPEGs that are 200 pixels in height:{"plugins":{"datasette-media":{"photo":{"sql":"select filepath, 200 as resize_height, 'jpeg' as output_format from apple_photos where uuid=:key","database":"photos"}}}}If you enable theenable_transformconfiguration option you can instead specify transform parameters at runtime using querystring parameters. For example:/-/media/photo/CF972D33?w=200to resize to a fixed width/-/media/photo/CF972D33?h=200to resize to a fixed height/-/media/photo/CF972D33?format=jpegto convert to JPEGThat option is added like so:{"plugins":{"datasette-media":{"photo":{"sql":"select filepath from apple_photos where uuid=:key","database":"photos","enable_transform":true}}}}The maximum allowed height or width is 4000 pixels. You can change this limit using the"max_width_height"option:{"plugins":{"datasette-media":{"photo":{"sql":"select filepath from apple_photos where uuid=:key","database":"photos","enable_transform":true,"max_width_height":1000}}}}ConfigurationIn addition to the different named content types, the following special plugin configuration setting is available:transform_threads- number of threads to use for running transformations (e.g. resizing). Defaults to 4.This can be used like this:{"plugins":{"datasette-media":{"photo":{"sql":"select filepath from apple_photos where uuid=:key","database":"photos"},"transform_threads":8}}}