{ "version": "https://jsonfeed.org/version/1", "title": "offbyone.tech", "home_page_url": "https://offbyone.tech/", "feed_url": "https://offbyone.tech/feed.json", "description": "A mostly tech-related blog, maybe.", "author": { "name": "Zach Green", "url": "https://offbyone.tech/" }, "items": [{ "id": "https://offbyone.tech/posts/lighthouse-circleci/", "url": "https://offbyone.tech/posts/lighthouse-circleci/", "title": "Running Lighthouse in CircleCI", "content_html": "

Running Lighthouse in CircleCI

\n

Update (October 2, 2018)

\n

The code in this post uses lighthouse v2; it needs to be slightly modified to work with lighthouse v3. To skip straight to a working v3 example, visit the example repo I posted, which has been updated: https://github.com/zgreen/lighthouse-circleci-example.

\n
\n

Recently I set up Lighthouse to run in CircleCI. At the time, I wasn't able to find many resources online about how to do this, so I'm posting my work here.

\n

Writing the Lighthouse tests

\n

Create a file for your tests. I'm not running a ton of tests at the moment, so I run them all in a single file, lighthouse.test.js.

\n

You'll need a pair of npm packages...

\n
npm install --save-dev lighthouse chrome-launcher
\n

And something to execute your tests. This example uses Jest:

\n
npm install --save-dev jest
\n
const lighthouse = require(\"lighthouse\"); // Node CLI for Lighthouse https://www.npmjs.com/package/lighthouse#using-the-node-cli\nconst chromeLauncher = require(\"chrome-launcher\"); // Launch Chrome from node
\n

Jest sets a default timeout of 5 seconds for each test. Lighthouse can take longer to run, so you should increase that timeout if you're using Jest:

\n
jest.setTimeout(60000); // Give it a minute, just in case.
\n

Next, you'll need a helper function for launching Chrome and running Lighthouse, and returning the audits:

\n
const launchChromeAndRunLighthouse = (\n  url,\n  opts = { chromeFlags: [] },\n  config = null\n) =>\n  chromeLauncher.launch({ chromeFlags: opts.chromeFlags }).then((chrome) => {\n    opts.port = chrome.port;\n    return lighthouse(url, opts, config).then((results) =>\n      chrome.kill().then(() => results)\n    );\n  });
\n

Finally, write a test! This example tests whether the first meaningful paint score for https://example.com is greater than or equal to 50:

\n
test(\"Meaningful first paint score\", () =>\n  launchChromeAndRunLighthouse(`https://example.com`).then(({ audits }) =>\n    expect(audits[\"first-meaningful-paint\"].score).toBeGreaterThanOrEqual(50)\n  ));
\n

Write as many of these as you want; Lighthouse returns a ton of useful data.

\n

Add an npm test script

\n

In package.json:

\n
\"scripts\": {\n  \"test\": \"jest\"\n}
\n

In this example, I'm running tests in Jest, so... that's all that's required.

\n

Execute these tests in CircleCI

\n

This example assumes the use of CircleCI 2.0.

\n

Create a file, .circleci/config.yml:

\n
# Javascript Node CircleCI 2.0 configuration file\n#\n# Check https://circleci.com/docs/2.0/language-javascript/ for more details\n#\nversion: 2\njobs:\n  build:\n    docker:\n      # specify the version you desire here\n      - image: circleci/node:9.8.0-browsers\n    working_directory: ~/repo\n    steps:\n      - checkout\n      # Download and cache dependencies\n      - restore_cache:\n          keys:\n            - v1-dependencies-\n            # fallback to using the latest cache if no exact match is found\n            - v1-dependencies-\n      - run: yarn install\n      - save_cache:\n          paths:\n            - node_modules\n          key: v1-dependencies-\n      - run: yarn test
\n

You can use the CircleCI CLI to run/test this out locally.

\n

All done

\n

That's it! Here's a repo with all of this put into action: https://github.com/zgreen/lighthouse-circleci-example

\n", "date_published": "2018-04-28T02:42:32Z" } ,{ "id": "https://offbyone.tech/posts/parsing-urls-from-text/", "url": "https://offbyone.tech/posts/parsing-urls-from-text/", "title": "Parsing URLs from text using a native web API", "content_html": "

Parsing URLs from text using a native browser API

\n

Here's one that that's a lot easier than it used to be.

\n

Say you're rendering a bunch of text, and that text may or may not contain one or more URLs. You'd like those URLs to be actual <a> tags when you render them, so that folks can click on them.

\n

It used to be, you'd have to do a little footwork, parsing the text for the protocol, pathname etc... an error prone process. Or you were smart about it and just relied on a npm module that handled all the edge cases and gave you a decent API.

\n

But, now you don't even need to write your own parsing logic nor do you need to add a dependency to handle it for you. You can use the URL browser API.

\n

If you're not familiar with it, URL is a really handy API, that takes in a URL and spits out a bunch of helpful properties:

\n
const url = new URL(\n  \"https://offbyone.tech/parsing-urls-from-text-using-native-web-tech\"\n);\nconsole.log(url);\n\n// URL {\n//   hash: \"\",\n//   host: \"offbyone.tech\"\n//   hostname: \"offbyone.tech\",\n//   href: \"https://offbyone.tech/parsing-urls-from-text-using-native-web-tech\",\n//   origin: \"https://offbyone.tech\",\n//   password: \"\",\n//   pathname: \"/parsing-urls-from-text-using-native-web-tech\",\n//   port: \"\",\n//   protocol: \"https:\",\n//   search: \"\",\n//   searchParams: URLSearchParams {  },\n//   username: \"\"\n// }
\n

This replaces a bunch of stuff that we used to need custom code for, but it's also super handy for parsing URLs:

\n
const text = `\nAut culpa sapiente autem quia enim. https://example.com Sequi consequatur nisi sapiente atque ut pariatur. Quibusdam veniam et repellendus ducimus eaque explicabo quia. Cumque quidem quaerat quia sit commodi voluptatem. Architecto libero et illum. Blanditiis https://duckduckgo.com modi quidem qui libero veniam in et. Amet autem fugiat nobis ex dolorem animi quidem. Non pariatur autem numquam et occaecati sapiente sit. Dolores hic fugit dolorem fuga voluptas. Possimus et cupiditate officiis voluptas. Voluptas qui minima sit sunt excepturi blanditiis dolore expedita.\n  `;\nconst words = ;\nreturn text.split(\" \")\n  .map((str, idx, arr) => {\n      const text = idx + 1 !== arr.length ? `${str} ` : str;\n      try {\n        const url = new URL(str); // If this doesn't throw an error, it's a URL!\n        return `<a href=\"${url.href}\">${text}</a>`;\n      } catch (err) {\n        // Error! It's not a URL, so we'll just proceed with it as a regular string\n        return text;\n      }\n    })\n    .join(\"\");
\n

This works because new URL() just throws an error if it receives anything other than a URL.

\n

It's worth noting that that snippet won't quite work in React unless you use dangerouslySetInnerHTML. Here's a React-safe approach:

\n
export default () => {\n  const text = `\nAut culpa sapiente autem quia enim. https://example.com Sequi consequatur nisi sapiente atque ut pariatur. Quibusdam veniam et repellendus ducimus eaque explicabo quia. Cumque quidem quaerat quia sit commodi voluptatem. Architecto libero et illum. Blanditiis https://duckduckgo.com modi quidem qui libero veniam in et. Amet autem fugiat nobis ex dolorem animi quidem. Non pariatur autem numquam et occaecati sapiente sit. Dolores hic fugit dolorem fuga voluptas. Possimus et cupiditate officiis voluptas. Voluptas qui minima sit sunt excepturi blanditiis dolore expedita.\n  `;\n  return (\n    <blockquote>\n      {text\n        .split(\" \")\n        .reduce((acc, str, idx, arr) => {\n          const text = idx + 1 === arr.length;\n          try {\n            const url = new URL(str); // If this doesn't throw an error, it's a URL!\n            acc.push(<a href={url.href}>{text}</a>);\n          } catch (err) {\n            // Error! It's not a URL, so we'll just proceed with it as a regular string\n            if (typeof acc[acc.length - 1] === \"string\") {\n              acc[acc.length - 1] = acc[acc.length - 1] + text;\n            } else {\n              acc.push(text);\n            }\n          }\n          return acc;\n        }, [])\n        .map((item) => item)}\n    </blockquote>\n  );\n};
\n

That's it! That's all you have to do. Browser support is very good, but doesn't include IE. If you need to support older browsers, polyfill.io can cover this one:

\n
<script\n  crossorigin=\"anonymous\"\n  src=\"https://polyfill.io/v3/polyfill.min.js?flags=gated&features=URL\"\n></script>
\n", "date_published": "2019-10-05T18:59:20Z" } ,{ "id": "https://offbyone.tech/posts/11ty-cloudflare-workers-github-actions/", "url": "https://offbyone.tech/posts/11ty-cloudflare-workers-github-actions/", "title": "Automatic static site deployment with 11ty, Cloudflare Workers, and GitHub actions", "content_html": "

Update (January 3, 2024)

\n

This is all way easier now. Here are the docs.

\n
\n

Automatic static site deployment with 11ty, Cloudflare Workers, and GitHub actions

\n

Time for my one blog post of the year! Approriately, it concerns my having completely reimplemented this blog's tech stack and workflow for the umpteenth time. This has become a more or less annual ritual. And, like many rituals, it is arguably totally pointless! Nevertheless!

\n

Having said that, I've achieved something with this workflow that I've been seeking more or less since I started this blog: a simple workflow wherein I write one blog post in Markdown, push it to my GitHub repo, and the whole site is then automatically rebuilt and deployed. This blog post will be the inaugural test run.

\n

What follows is a brief meta-tutorial explaining my workflow, and linking to external guides that I used to get set up. If you're completely unfamiliar with everything in the title of this post, you might still be able to get an idea of how it all fits together by reading through this. That said, this post will probably be most useful to folks that know how to use npm and that have a passing familiarity with some of the tech in the post title.

\n

Requirements

\n\n

11ty

\n

11ty is static-site generator. If you're totally unfamiliar with what that is, it basically means you can author your pages in Markdown and build a static HTML version of those pages. If you're already familiar, then 11ty is basically a lot like other static site generators, except that it's a bit simpler than some of the most popular solutions (like Next.js, which this blog used to use, or Gatsby, which this blog also used to use...) currently out there. Get started with it here.

\n

Cloudflare Workers

\n

This is what I'm using to host the static assets (in my case, just plain old HTML). Cloudflare Workers is a serverless execution environment that runs on Cloudflare's network. The specific workers platform is Workers Sites, which is built especially for deploying static sites.

\n

GitHub actions

\n

GitHub Actions is a CI/CD platform; it lets you automate all kinds of things. In my case, I use it to automate building the blog, and then publishing it to Cloudflare.

\n

Step 1: Set up the blog

\n

Using 11ty, this just means following the getting started docs. But 11ty isn't a requirement; you could use any static site generator, or even just author the HTML by hand (really!).

\n

Step 2: Set up Cloudflare Workers

\n

I'm using a modified version of Cloudflare's Workers Sites, which runs on Cloudflare workers. You can either follow these docs to start from an existing static site, or these to start from scratch.

\n

That's it, if you like.

\n

You don't need to set up GitHub actions or even use GitHub at all if you want to publish a static site to Cloudflare Workers. As noted in the docs, you can simply run wrangler publish once you're all set up, and your site will be published to a publically viewable URL.

\n

GitHub actions

\n

The advantage of using a GitHub action is that I can push a new blog post or page to my GitHub repo for this site, and the site will be rebuilt and published automatically. It's just a workflow improvement.

\n

To set up the action, I added this file to .github/workflows/deploy.yml:

\n
name: deploy\n\non:\n  push:\n    branches:\n      - \"master\"\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    name: deploy\n    steps:\n      - uses: actions/checkout@v2\n\n      - run: npm ci\n      - run: npm run build\n\n      - name: Publish\n        uses: cloudflare/wrangler-action@1.3.0\n        with:\n          apiToken: ${{ secrets.CF_API_TOKEN }}\n        env:\n          CF_ACCOUNT_ID: ${{ secrets.CF_API_TOKEN }}\n          USER: root
\n

This Yaml conforms to the required syntax for GitHub actions; it's taken from here. This action installs the necessary dependencies from npm, builds the site, and publishes it.

\n

Secrets

\n

You can use GitHub secrets to store encrypted environment variables. The advantage of using secrets in this case is that I can store CF_API_TOKEN without writing it directly into the wrangler.toml file, where it might be unintentionally exposed.

\n

You can set secrets for a GitHub repository by visiting Settings > Secrets in the repo's navigation.

\n

You might note that the Yaml snippet is slightly different than the example given in the action's GitHub README. This is because I chose not to include my Cloudflare workers account id in the site's wrangler.toml file. According to this issue it's safe to do so, but you can also use GitHub secrets and a Cloudflare workers API token (with appropriate permissions) to do the same thing without potentially exposing your account ID.

\n

It works!

\n

With this action in place, your site will automatically be rebuilt and published to Cloudflare on any pushes to the master branch. You can modify that branch name to be something else, and/or add additional branch names.

\n

This should be all you need to get going; read on for some additional tips and tricks.

\n

Further notes

\n

Skipping step #2

\n

You can actually skip the step of manually setting up a Cloudflare Workers site, and use the GitHub action all by itself to do this. See this repo for an example. You'll note that repository has no workers-site/index.js file at all; it's handled by the Github Action directly.

\n

Customizing the workers site behavior

\n

You may, like me, need to customize some aspect of your static site at the Cloudflare worker level. This is the main reason for setting up a Workers Site as outlined in step #2.

\n

Redirects

\n

I had some redirects set up with Next.js, and 11ty, being a much more basic tool, has no way to pull this off. Fortunately, it's quite easy to do in Cloudflare Workers. Here's my entire workers/index.js file, for reference:

\n
import {\n  getAssetFromKV,\n  mapRequestToAsset,\n} from \"@cloudflare/kv-asset-handler\";\n\nconst DEBUG = false;\n\naddEventListener(\"fetch\", (event) => {\n  try {\n    event.respondWith(handleEvent(event));\n  } catch (e) {\n    if (DEBUG) {\n      return event.respondWith(\n        new Response(e.message || e.toString(), {\n          status: 500,\n        })\n      );\n    }\n    event.respondWith(new Response(\"Internal Error\", { status: 500 }));\n  }\n});\n\nasync function handleEvent(event) {\n  const url = new URL(event.request.url);\n  const { pathname, search, hash, origin } = url;\n  // redirects\n  switch (pathname) {\n    case \"/json\":\n      return Response.redirect(`${origin}/feed.json`, 301);\n    case \"/lighthouse-circleci\":\n      return Response.redirect(`${origin}/posts/lighthouse-circleci`, 301);\n    case \"/posts/parsing-urls-from-text-using-native-web-tech\":\n      return Response.redirect(`${origin}/posts/parsing-urls-from-text`, 301);\n    case \"/rss\":\n      return Response.redirect(`${origin}/feed.xml`, 301);\n    // no default\n  }\n  let options = {};\n\n  /**\n   * You can add custom logic to how we fetch your assets\n   * by configuring the function `mapRequestToAsset`\n   */\n  // options.mapRequestToAsset = handlePrefix(/^\\/docs/)\n\n  try {\n    if (DEBUG) {\n      // customize caching\n      options.cacheControl = {\n        bypassCache: true,\n      };\n    }\n    return await getAssetFromKV(event, options);\n  } catch (e) {\n    // if an error is thrown try to serve the asset at 404.html\n    if (!DEBUG) {\n      try {\n        let notFoundResponse = await getAssetFromKV(event, {\n          mapRequestToAsset: (req) =>\n            new Request(`${new URL(req.url).origin}/404/index.html`, req),\n        });\n\n        return new Response(notFoundResponse.body, {\n          ...notFoundResponse,\n          status: 404,\n        });\n      } catch (e) {}\n    }\n\n    return new Response(e.message || e.toString(), { status: 500 });\n  }\n}
\n

You'll note the switch block in the handleEvent function. That's what handles the redirects.

\n

Feeds

\n

My Next.js-powered site had json and RSS feeds, generated dynamically in Node. But there's no reason these feeds can't also be generated statically along with the rest of the site. Doing so is easy enough using @11ty/eleventy-plugin-rss.

\n

Custom domain

\n

During testing, I was deploying the site to my workers.dev subdomain. I set up my custom domain using Cloudflare's DNS management (the actual domain I purchased elsewhere). I had to add this line to my wrangler.toml:

\n
route = \"offbyone.tech/*\"
\n

Next.js -> 11ty

\n

I still really like Next.js, and it remains my go-to framework for any project that needs such a thing. But for running a blog, it wasn't great. There is an example in their repo, but managing things simple things like post metadata, feeds, and having a list of all posts on the blog home page always felt harder to me than it needed to be. 11ty is just simpler; it has fewer moving parts, and it does its primary task—building a static site—quickly and easily. The major trade off is that by switching to a completely static build, I lose the server-side Node.js environment I had with Next.js. (Next.js does have a really good static export feature, but I ran the blog with server-side rendering in Node.) Fortunately, the use of Cloudflare Workers seems to more than make up for this loss; I can do everything in a worker I was already using the Node server for, plus, it seems, quite a bit more.

\n

Vercel -> Cloudflare

\n

For a while, this blog was hosted on Vercel. I like Vercel, and have been using the platform since their v1. But the platform has had a lot of churn in a really short period of time. Their first version was defined by a really nice CLI and the ability to deploy pretty much any kind of application using a Docker container. The second version moved to an entirely serverless model, which still suited my needs well. But along the way the CLI decayed, to the point where it was not as fun to use. There were also a ton of pricing changes, and I could never really sort what size bill I might receive if the blog were suddenly to get a lot of traffic. Cloudflare, I'm hoping, will be a bit more stable. It's also cheaper (I'm paying for a $5/month Cloudflare Workers account) and the site now loads a lot faster.

\n

That's it. Thanks for reading!

\n", "date_published": "2020-12-23T11:54:50Z" } ,{ "id": "https://offbyone.tech/posts/simpler-jest-mocking/", "url": "https://offbyone.tech/posts/simpler-jest-mocking/", "title": "Simpler Jest mocking", "content_html": "

Simpler Jest mocking

\n

There are a lot of ways to mock things in jest. And that's not counting spies, which are like mocks, but different.

\n

I still probably haven't read all the mocking-related Jest docs. Why would I do that? Anyway, the docs describe the preferred way to mock, and it's super simple:

\n
\n

If the module you are mocking is a Node module (e.g.: lodash), the mock should be placed in the mocks directory adjacent to node_modules

\n
\n

Nice. I've used this feature a lot. For stuff like this:

\n
// ./__mocks__/axios.js\nimport mockAxios from \"jest-mock-axios\";\nexport default mockAxios;
\n

Now when I import axios from 'axios' in a test file... I'm not actually importing it. I'm importing the mock.

\n

On the one hand, this is really nice. I can write one mock file, and now anytime I'm in a test environment, axios is automatically mocked for me, and I've got some custom test APIs I can run. 🆒

\n

But it turns out this is kind of a pain in the ass sometimes! Specifically:

\n
    \n
  1. If you don't want to mock the module, or
    2. \n
  2. if you want to mock the module differently, or
    3. \n
  3. you forgot that you mocked the module in the first place.
    4. \n
\n

The thing that sucks about this is that, in the context of your text file, the mock is implicit; there's no indication that module is mocked. When you look at the file for the first time, or come back to it after not having looked at it in a while, and see this:

\n
// my.test.tsx\nimport axios from \"axios\";
\n

...you're probably going to assume that that file has imported the axios module. But it hasn't!

\n

This can get even worse if you're mocking your own modules, where the docs recommend this:

\n
\n

Manual mocks are defined by writing a module in a mocks/ subdirectory immediately adjacent to the module. For example, to mock a module called user in the models directory, create a file called user.js and put it in the models/mocks directory. Note that the mocks folder is case-sensitive, so naming the directory MOCKS will break on some systems.

\n
\n

Do this an you'll end up with a bunch of __mocks__ directories all over your codebase.

\n

You may, as I have, come to regret this choice, especially if you've already written a lot of tests. Read the docs. There's a simpler way:

\n
// my.test.ts\nimport axios from \"axios\";\n\njest.mock(\"axios\");\n\ntest(\"example test with a mock\", () => {\n  expect(axios).toHaveBeenCalled();\n});
\n

The nice thing about this is that the mock is explicit! It says .mock right there in the file! And that's all you need to do. No magic. Mocks are inherently weird and confusing—avoid them if you can—because the code you import is not really the code that gets tested. Sort of!

\n

Keep it simple, that's all.

\n

Credit to this post, which set me straight a little bit.

\n", "date_published": "2020-12-29T18:21:00Z" } ,{ "id": "https://offbyone.tech/posts/secret-urls-with-11ty/", "url": "https://offbyone.tech/posts/secret-urls-with-11ty/", "title": "Secret URLs with 11ty", "content_html": "

Secret URLs with 11ty

\n

I sometimes want to be able to create secret pages on this site; I want a unique URL that I can share with someone, but I basically don't want anyone to be able to find the page unless I've shared the URL with them. This is basically how GitHub secret gists work:

\n
\n

Secret gists aren't private. If you send the URL of a secret gist to a friend, they'll be able to see it. However, if someone you don't know discovers the URL, they'll also be able to see your gist.

\n
\n

It's quite simple to do with 11ty. Here's a working example, and here's how I built it:

\n
    \n
  1. Create a new subdirectory in your site folder. Mine is site/secrets/.
    2. \n
  2. Generate a unique, URL-safe ID. Nano ID is great for this. You can just run npx nanoid if you have Node.js installed.
    3. \n
  3. Create a markdown file, with this ID as the file name, inside your secrets directory. The example file I'm using here is: site/secrets/ALtX3rwMv5EXx8x4vUGnA.md.
    4. \n
  4. Add some metadata and text. You can put whatever you like here—the only important thing is that you add a specific tag. On this site, I just use tags: ["secret"].
    5. \n
  5. On the 11ty layout template for your page, add the following snippet your HTML <head>:
    6. \n
\n
`\n${\n  tags && tags.includes(\"secret\")\n    ? `<meta name=\"robots\" content=\"noindex, nofollow\" />`\n    : \"\"\n}\n`;
\n

That ensures the page won't be indexed by search engines, and that search engines won't follow links on the page.

\n", "date_published": "2021-04-09T14:29:07Z" } ,{ "id": "https://offbyone.tech/posts/useful-commands-from-my-shell-history/", "url": "https://offbyone.tech/posts/useful-commands-from-my-shell-history/", "title": "Useful Commands From My Shell History", "content_html": "

Useful commands from my shell history

\n

My shell history is pretty boring, mostly a lot of npm and git, but there are a handful specific commands I need infrequently, and that I always pull up by Ctrl+R-ing through my shell because the commands themselves are too long and weird to commit to memory.

\n

I'm documenting those here, should my shell history ever be lost.

\n

Convert a web extension to a Safari web extension:

\n

Safari "supports" web extensions, except you still have to convert them and build them with Xcode. I don't quite know what the logic is for when this command has to be run/rerun—it seems to be whenever a new file is added. Changed files get picked up by Xcode, I think? I really don't like building web extensions for Safari.

\n
xcrun safari-web-extension-converter web-extension/path --project-location web-extension/safari --macos-only
\n

Convert an .mp4 video to a .webm video:

\n
ffmpeg -i VIDEO_NAME.mp4 -c:v libvpx-vp9 -pix_fmt yuva420p VIDEO_NAME.webm
\n

Sync a specific file type to AWS S3, with multi-factor authentication enabled:

\n

For example, this command will sync only .json files:

\n
aws s3 sync . s3://your/directory/path --exclude \"*.*\"  --include \"*.json\" --profile mfa --dryrun
\n

Note: that command has the --dryrun flag. It won't actually do anything—it will just tell you what it will do without flag. Remove --dryrun to do it for real.

\n

AWS multi-factor auth:

\n

Related docs

\n
aws sts get-session-token --serial-number SERIAL_NUMBER_HERE --token-code TOKEN_CODE_HERE
\n", "date_published": "2023-09-29T13:06:33Z" } ,{ "id": "https://offbyone.tech/posts/the-search-term-you-want-is-share-target/", "url": "https://offbyone.tech/posts/the-search-term-you-want-is-share-target/", "title": "The search term you want is: `share_target`", "content_html": "

The search term you want is: share_target

\n

Sometimes you don't know the name of the thing you're looking for; sometimes you have a question, but don't know how to ask it. And only when you discover the exact search term does that unlock the information you've been trying to find.

\n

Here's an example. On macOS, lots of applications offer this native share menu. Here's a screenshot from Safari:

\n

\"Screenshot

\n

Initially I wasn't sure if "share menu" was the right term for that menu, but it looks like it is.

\n

But what I was wondering was: was it possible to add a webapp to that menu? For example, if I have a webapp that can receive images (like Squoosh), could I "add" that webapp as an option in the macOS share menu? It seems like I should be able to.

\n

I searched for things like "add webapp to share menu macos", "add item to share menu macos", and other similar permutations. This generally just yielded posts with instructions on how to modify the share menu items as an end user—i.e. how to add or remove specific native applications. But there was nothing I could find about programatically adding a webapp to that menu.

\n

I also tried searches that included pwa and progressive web app, since it seemed possible that this functionality might be tied to "installing" the webapp somehow. No luck. Every few months I'd search around, find nothing useful, and then give up.

\n

But then one day, I found the term I wanted. I actually don't remember how I found it. But the term you want is share_target! Here's the MDN link. (It's entirely possible I was just surfing around MDN and then stumbled across this—I've accidentally learned a number of things that way.)

\n

Here are a few other helpful links:

\n\n

It turns out the exact functionality I wanted has already been spec'd out! Great!

\n

Unfortunately it seems not to be supported by Apple. I actually can't find any documentation that officially says it is or isn't supported... but adding share_target to a manifest.json doesn't have any effect. The closest documentation I could find was this WebKit GitHub issue, which suggests that the WebKit team is relatively neutral on the issue, but also suggests that they haven't actually implemented it.

\n

Oh well. At least now I know what to search for. The official macOS way to add items to the native share menu seems to be add a "Share Extension" as a new "target" in Xcode:

\n

\"Screenshot

\n

Documentation about this is also pretty scant.

\n", "date_published": "2024-01-23T13:51:07Z" } ,{ "id": "https://offbyone.tech/posts/the-search-term-you-want-is-time-stretching/", "url": "https://offbyone.tech/posts/the-search-term-you-want-is-time-stretching/", "title": "The search term you want is: `time stretching`", "content_html": "

The search term you want is: time stretching

\n

Here's another case where discovering the right search term unlocks a wealth of information.

\n

I've used the Web Audio API for a number of different projects at this point, and I'm pretty familiar with it. But a couple years ago I discovered something surprising: adjusting the playback rate of an AudioBufferSourceNode will also change the pitch of the audio.

\n

This was surprising, because when you change the playback rate of an HTMLMediaElement (e.g. an <audio> or <video> element), the pitch of the audio does not change.

\n

I think it's safe to say that most folks that work with audio on the web only ever need to use the <audio> tag. Most of the time, you have an audio src URL, like https://example.com/my.mp3, and you just need to play it. The <audio> tag works great for this simple, common use case. The Web Audio API is much lower level. You might use it if you wanted to add sound effects to game, build a synthesizer in the browser, or maybe build a custom audio player with some very specific requirements.

\n

It's also pretty common that a user might want to adjust the playback rate of the audio. If they want to get through audio a bit faster, they'll speed it up, and if they need more time to process it (for example, if it's in a foreign language, or the speakers are talking unusually fast), they'll slow it down. And if you're working with an <audio> tag, all you have to do is adjust the playback rate; the audio will speed up or slow down, but the user will notice no change in pitch.

\n

Not so with the Web Audio API—a playback rate above 1 will give you a chipmunk voice, and playback rate below 1 will give you a drunk voice (reliably hilarious).

\n

What I didn't realize—what I never had to think about—was that the <audio> tag was actually doing some extra work for me whenever I adjusted the playback rate. Think about it: if you play an analog audio source, like tape or vinyl, faster or slower than expected, you get the chipmunk/drunk effect. You can also think of it as an actual wave: increasing the speed of wave means shortening the wavelength (and thus a higher pitch). So why doesn't that happen with <audio>? Well, it's right there in the MDN docs:

\n
\n

The pitch of the audio is corrected by default. You can disable pitch correction using the HTMLMediaElement.preservesPitch property.

\n
\n

Ah. Does AudioBufferSourceNode have this property, or something like it?

\n

No. I've been subscribed to that issue for about two years now. My guess is we'll get something eventually, but I'm not holding my breath.

\n

Searching in vain for a simple, native solution, I tried variations of "web audio change playback rate without changing pitch". Here's a Stack Overflow question that asks the very same thing (note that the answers are not very helpful).

\n

But the term you want is time stretching. Here's Wikipedia:

\n
\n

Time stretching is the process of changing the speed or duration of an audio signal without affecting its pitch.

\n
\n

You can search this on npm to get started, but I should warn you: there really is no easy way to do this. There's no native solution, and no library I've ever found that implements it in a simple and straightforward way (probably because it's neither a simple nor straightforward problem).

\n", "date_published": "2024-01-30T13:27:58Z" } ] }