defmodule Image.Social do
@moduledoc """
Functions to introspect standard image sizes for
various social media platforms.
"""
alias Vix.Vips.Image, as: Vimage
@typedoc """
The social media platform image usage.
"""
@type image_usage :: atom()
@typedoc """
The known social media platforms.
"""
@type platform ::
:facebook
| :twitter
| :linkedin
| :pinterest
| :instagram
| :tumblr
| :youtube
| :snapchat
| :tiktok
# Before Version 1.0, this content will move from being a static
# list to a dynamic one that can be updated at runtime
# Facebook: https://www.facebook.com/help/125379114252045?helpref=faq_content
# https://www.socialpilot.co/blog/social-media-image-sizes
# https://blog.hootsuite.com/social-media-image-sizes-guide/
@social_sizes %{
facebook: %{
default: :post,
profile: "170x170",
cover_desktop: "820x312",
cover_mobile: "640x360",
post: "1200x630",
banner: "1200x630",
story: "1080x1920"
},
twitter: %{
profile: "400x400",
cover: "1500x500",
shared: "900x450",
stream: "440x220"
},
linkedin: %{
profile: "400x400",
cover: "1584x396",
company_logo: "400x400",
blog: "1200x627"
},
pinterest: %{
profile: "165x165",
cover: "800x450",
pin: "1080x1920",
board: "222x150"
},
instagram: %{
profile: "320x320",
cover: "1080x1920",
photo: %{
landscape: "1080x596",
portrait: "1080x1350",
square: "1080x1080"
},
thumb: "161x161",
story: "1080x1920",
carousel: %{
landscape: "1080x566",
portrait: "1080x1350",
square: "1080x1080"
}
},
tumblr: %{
profile: "128x128",
banner: "3000x1055",
post: "500x750"
},
youtube: %{
cover: "2560x1440",
profile: "800x800",
banner: "2048x1152",
thumbnail: "1280x720"
},
snapchat: %{
photo: "1080x1920",
share: "750x1334"
},
tiktok: %{
profile: "20x20",
video: "1080x1920"
}
}
@social_platforms Map.keys(@social_sizes)
@doc """
Return the map of social media image
sizes.
The returned map of maps is of a standard form:
* The first key is the platform name (ie `:twitter`)
* The second key is the image type for the platform (ie `:profile`)
* The third level is optional. But if it exists it must
have three keys: `:landscape`, `:portrait` and `:square`
The values are all of the form "WxH" where `W` is the
width in pixels and `H` is the height in pixels.
"""
def media_sizes do
@social_sizes
end
@doc """
Returns a list of known social
platforms.
### Example
"""
@spec known_platforms :: [platform()]
def known_platforms do
@social_platforms
end
@doc """
Returns the image types for the given
social platform.
### Arguments
* `platform` is any known social platform.
See `Image.Social.known_platforms/0`.
### Returns
* A list of images uses available for the
platform.
### Example
"""
@spec image_usages(platform()) :: [image_usage()]
def image_usages(platform) when platform in @social_platforms do
media_sizes()
|> Map.fetch!(platform)
|> Map.delete(:default)
|> Map.keys()
end
@doc """
Returns the default image type that an
image is resized to for a given platform
is no `:type` parameter is provided.
### Arguments
* `platform` is any known social platform.
See `Image.Social.known_platforms/0`.
### Returns
* The default image type for the platform.
### Example
"""
@spec default_image_usage(platform()) :: image_usage()
def default_image_usage(platform) when platform in @social_platforms do
media_sizes()
|> Map.fetch!(platform)
|> Map.get(:default)
end
@doc """
Resize an image for a particular social
platform and usage.
This function:
* Resizes an image to the correct dimensions, including being
image aspect aware
* Converts to the sRGB color space
* Minimises metadata (retains only Artist and Copyright)
### Arguments
* `image` is any `t:Vix.Vips.Image.t/0`
* `platform` is the name of a known social
media platform. See `Image.Social.known_platforms/0`.
* `options` is a keyword list of options.
### Options
* `:type` is the image type within the social
platform for which the image should be resized. See
`Image.Social.image_usages/1`
* All other options are passed to `Image.thumbnail!/3`.
### Returns
* `{:ok, resized_image}` or
* `{:error, reason}`
"""
@spec resize(Vimage.t(), platform(), Keyword.t()) ::
{:ok, Vimage.t()} | {:error, Image.error_message()}
def resize(image, platform, options \\ [])
def resize(%Vimage{} = image, platform, options) when platform in @social_platforms do
{usage, options} = Keyword.pop(options, :usage, :default)
options = Keyword.put_new(options, :crop, :attention)
aspect = Image.aspect(image)
platform = Map.fetch!(media_sizes(), platform)
with {:ok, size} <- get_image_size(platform, usage, aspect) do
image
|> Image.thumbnail!(size, options)
|> Image.to_colorspace!(:srgb)
|> Image.minimize_metadata()
end
end
def resize(%Vimage{} = _image, platform, _options) do
{:error, unknown_platform_error(platform)}
end
@doc """
Resize an image for a particular social
platform and usage.
This function:
* Resizes an image to the correct dimensions, including being
image orientation aware
* Converts to the sRGB color space
* Minimises metadata (retains only Artist and Copyright)
### Arguments
* `image` is any `t:Vix.Vips.Image.t/0`
* `platform` is the name of a known social
media platform. See `Image.Social.known_platforms/0`.
* `options` is a keyword list of options.
### Options
* `:type` is the image type within the social
platform for which the image should be resized. See
`Image.Social.image_usages/1`
* All other options are passed to `Image.thumbnail!/3`.
## Returns
* `resized_image` or
* Raises an exception.
"""
@spec resize!(Vimage.t(), platform(), Keyword.t()) ::
Vimage.t() | no_return
def resize!(%Vimage{} = image, platform, options \\ []) do
case resize(image, platform, options) do
{:ok, image} -> image
{:error, reason} -> raise Image.Error, reason
end
end
# ---- Helpers -----
defp get_image_size(platform, :default = type, orientation) do
default = Map.get(platform, type, {nil, type})
get_image_size(platform, default, orientation)
end
defp get_image_size(_platform, {nil, usage}, _orientation) do
{:error, unknown_usage_error(usage)}
end
defp get_image_size(platform, usage, orientation) when is_map_key(platform, usage) do
platform
|> Map.get(usage)
|> resolve_orientation(orientation)
end
defp get_image_size(_platform, usage, _orientation) do
{:error, unknown_usage_error(usage)}
end
defp resolve_orientation(size, _orientation) when is_binary(size) do
{:ok, size}
end
defp resolve_orientation(sizes, orientation) when is_map_key(sizes, orientation) do
{:ok, Map.fetch!(sizes, orientation)}
end
defp resolve_orientation(_sizes, orientation) do
{:error, unknown_orientation_error(orientation)}
end
defp unknown_platform_error(platform) do
"Unknown social platform #{inspect(platform)}"
end
defp unknown_usage_error(:default) do
"No :default usage is configured"
end
defp unknown_usage_error(usage) do
"Unknown image usage #{inspect(usage)}"
end
defp unknown_orientation_error(orientation) do
"Unknown orientation #{inspect(orientation)}"
end
end
